Skip to main content
Module

x/kvdex/mod.ts>Collection

High-level abstraction layer for Deno KV 🦕📁
oliver-oloughlin/kvdex
Go to Latest
class Collection
Re-export
import { Collection } from "https://deno.land/x/kvdex@v0.29.0/mod.ts";

Constructors

new
Collection(
kv: Deno.Kv,
key: KvKey,
queueHandlers: QueueHandlers,
idempotentListener: IdempotentListener,
model: Model<TInput, TOutput>,
options?: TOptions,
)

Type Parameters

TInput
TOutput extends KvValue
TOptions extends CollectionOptions<TOutput>

Properties

private
idempotentListener: IdempotentListener
private
kv: Deno.Kv
private
queueHandlers: QueueHandlers
readonly
_idGenerator: IdGenerator<TOutput>
readonly
_isIndexable: boolean
readonly
_isSerialized: boolean
readonly
_keepsHistory: boolean
readonly
_keys: CollectionKeys
readonly
_model: Model<TInput, TOutput>
readonly
_primaryIndexList: string[]
readonly
_secondaryIndexList: string[]
readonly
_serializer: Serializer

Methods

private
constructDocument(unnamed 0: Deno.KvEntryMaybe<any>)

Construct a document from an entry.

private
deleteDocuments(ids: KvId[], recordHistory: boolean)

Delete documents by id.

private
setDocument(
id: KvId | null,
options: SetOptions | undefined,
): Promise<CommitResult<TOutput> | Deno.KvCommitError>

Set a document entry in the KV store.

private
updateDocument(
options: UpdateOptions | undefined,
): Promise<CommitResult<TOutput> | Deno.KvCommitError>

Update a document entry with new data.

protected
handleMany<T>(
prefixKey: KvKey,
fn: (doc: Document<TOutput>) => T,
options: ListOptions<Document<TOutput>> | undefined,
)

Perform operations on lists of documents in the collection.

add(value: ParseInputType<TInput, TOutput>, options?: SetOptions)

Adds a new document to the KV store with a generated id.

Does not overwrite existing documents with coliiding id.

addMany(values: ParseInputType<TInput, TOutput>[], options?: SetOptions): Promise<ManyCommitResult | Deno.KvCommitError>

Adds multiple documents to the KV store with generated ids.

count(options?: ListOptions<Document<TOutput>>)

Counts the number of documents in the collection.

countBySecondaryIndex<K extends SecondaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
)

Counts the number of documents in the collection by a secondary index.

delete(...ids: KvId[])

Deletes one or more documents with the given ids from the KV store.

deleteByPrimaryIndex<K extends PrimaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
options?: FindOptions,
)

Delete a document by a primary index.

deleteBySecondaryIndex<K extends SecondaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
)

Delete documents by a secondary index. The method takes an optional options argument that can be used for filtering of documents, and pagination.

deleteHistory(id: KvId)

Delete the version history of a document by id.

deleteMany(options?: AtomicListOptions<Document<TOutput>>)

Deletes multiple documents from the KV store according to the given options.

If no options are given, all documents are deleted.

deleteUndelivered(id: KvId)

Delete an undelivered document entry by id from the collection queue.

enqueue<T extends KvValue>(data: T, options?: EnqueueOptions)

Add data to the collection queue to be delivered to the queue listener via db.collection.listenQueue(). The data will only be received by queue listeners on the specified collection and topic. The method takes an optional options argument that can be used to set a delivery delay and topic.

find(id: KvId, options?: FindOptions)

Finds a document with the given id in the KV store.

findByPrimaryIndex<K extends PrimaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
options?: FindOptions,
)

Find a document by a primary index.

findBySecondaryIndex<K extends SecondaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
)

Find documents by a secondary index. Secondary indices are not unique, and therefore the result is an array of documents. The method takes an optional options argument that can be used for filtering of documents, and pagination.

findHistory(id: KvId, options?: ListOptions<HistoryEntry<TOutput>>)

Retrieve the version history of a document by id.

A history entry contains a timestamp, type of either "write" or "delete", and a copy of the document value if the type is "write".

findMany(ids: KvId[], options?: FindManyOptions)

Finds multiple documents with the given array of ids in the KV store.

findUndelivered<T extends KvValue = KvValue>(id: KvId, options?: FindOptions)

Find an undelivered document entry by id from the collection queue.

forEach(fn: (doc: Document<TOutput>) => unknown, options?: ListOptions<Document<TOutput>>)

Executes a callback function for every document according to the given options.

If no options are given, the callback function is executed for all documents in the collection.

forEachBySecondaryIndex<K extends SecondaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
fn: (doc: Document<TOutput>) => unknown,
)

Executes a callback function for every document by a secondary index and according to the given options.

If no options are given, the callback function is executed for all documents matching the index.

getMany(options?: ListOptions<Document<TOutput>>)

Retrieves multiple documents from the KV store according to the given options.

If no options are given, all documents are retrieved.

listenQueue<T extends KvValue = KvValue>(handler: QueueMessageHandler<T>, options?: QueueListenerOptions)

Listen for data from the collection queue that was enqueued with db.collection.enqueue(). Will only receive data that was enqueued to the specific collection queue. Takes a handler function as argument.

map<T>(fn: (doc: Document<TOutput>) => T, options?: ListOptions<Document<TOutput>>)

Executes a callback function for every document according to the given options.

If no options are given, the callback function is executed for all documents in the collection.

The results from the callback function are returned as a list.

mapBySecondaryIndex<T, K extends SecondaryIndexKeys<TOutput, TOptions>>(
index: K,
value: CheckKeyOf<K, TOutput>,
fn: (doc: Document<TOutput>) => T,
)

Executes a callback function for every document by a secondary index and according to the given options.

If no options are given, the callback function is executed for all documents matching the index.

The results from the callback function are returned as a list.

set(
id: KvId,
options?: SetOptions,
)

Adds a new document with the given id to the KV store.

Does not overwrite existing documents with coliiding id.

setDoc(
docId: KvId,
idKey: KvKey,
value: TOutput,
options: SetOptions | undefined,
): Promise<CommitResult<TOutput> | Deno.KvCommitError>

Inner set document.

update<T extends UpdateOptions>(
id: KvId,
data: UpdateData<TOutput, T["strategy"]>,
options?: T,
): Promise<CommitResult<TOutput> | Deno.KvCommitError>

Updates a document with the given id in the KV store.

By default, the merge strategy is used when available, falling back to replace for primitive types and built-in objects (Date, RegExp, etc.). For plain objects, the merge-shallow strategy is also supported.

updateByPrimaryIndex<K extends PrimaryIndexKeys<TOutput, TOptions>, T extends UpdateOptions>(
index: K,
value: CheckKeyOf<K, TOutput>,
data: UpdateData<TOutput, T["strategy"]>,
options?: T,
): Promise<CommitResult<TOutput> | Deno.KvCommitError>

Update a document by a primary index.

updateBySecondaryIndex<K extends SecondaryIndexKeys<TOutput, TOptions>, T extends UpdateManyOptions<Document<TOutput>>>(
index: K,
value: CheckKeyOf<K, TOutput>,
data: UpdateData<TOutput, T["strategy"]>,
options?: T,
)

Update documents in the collection by a secondary index.

updateMany<T extends UpdateManyOptions<Document<TOutput>>>(value: UpdateData<TOutput, T["strategy"]>, options?: T)

Update the value of multiple existing documents in the collection.

upsert<TIndex extends PrimaryIndexKeys<TOutput, TOptions>, TUpsertOptions extends UpsertOptions>(input: UpsertInput<TInput, TOutput, TIndex, TUpsertOptions["strategy"]>, options?: TUpsertOptions)

Update an existing document by either id or primary index, or set a new document entry if no document with matching id/index exists.

When upserting by primary index, an id can be optionally specified which will be used when setting a new document entry, otherwise an id will be generated.

watch(
id: KvId,
fn: (doc: Document<TOutput> | null) => unknown,
options?: WatchOptions,
)

Listen for live changes to a single document by id.

watchMany(
ids: KvId[],
fn: (doc: (Document<TOutput> | null)[]) => unknown,
options?: WatchOptions,
)

Listen for live changes to an array of specified documents by id.

deprecated
write(
id: KvId,
options?: SetOptions,
)

Write a document to the KV store.

Sets a new document entry if no matching id already exists, overwrites the exisiting entry if it exists.

Does not overwrite existing entries if there is a primary index collision.