Replicache
Classes
Interfaces
- AsyncIterableIteratorToArray
- ExperimentalKVRead
- ExperimentalKVStore
- ExperimentalKVWrite
- LogSink
- ReadTransaction
- ReplicacheOptions
- RequestOptions
- ScanResult
- SubscribeOptions
- WriteTransaction
Type Aliases
ClientID
Ƭ ClientID: string
The ID describing a client.
ClientStateNotFoundReason
Ƭ ClientStateNotFoundReason: { type: "NotFoundOnServer" } | { type: "NotFoundOnClient" }
The reason onClientStateNotFound was called.
ClientStateNotFoundResponse
Ƭ ClientStateNotFoundResponse: Object
In certain scenarios the server can signal that it does not know about the client. For example, the server might have deleted the client.
Type declaration
| Name | Type |
|---|---|
error | "ClientStateNotFound" |
CreateIndexDefinition
Ƭ CreateIndexDefinition: IndexDefinition & { name: string }
ExperimentalCreateKVStore
Ƭ ExperimentalCreateKVStore: (name: string) => ExperimentalKVStore
Type declaration
▸ (name): ExperimentalKVStore
Factory function for creating Store instances.
The name is used to identify the store. If the same name is used for multiple stores, they should share the same data. It is also desirable to have these stores share an RWLock.
This type is experimental and might be removed or changed in the future without following semver versioning. Please be cautious.
Parameters
| Name | Type |
|---|---|
name | string |
Returns
ExperimentalDiff
Ƭ ExperimentalDiff: ExperimentalIndexDiff | ExperimentalNoIndexDiff
Describes the changes that happened to Replicache after a WriteTransaction was committed.
This type is experimental and may change in the future.
ExperimentalDiffOperation
Ƭ ExperimentalDiffOperation<Key>: ExperimentalDiffOperationAdd<Key> | ExperimentalDiffOperationDel<Key> | ExperimentalDiffOperationChange<Key>
The individual parts describing the changes that happened to the Replicache data. There are three different kinds of operations:
add: A new entry was added.del: An entry was deleted.change: An entry was changed.This type is experimental and may change in the future.
Type parameters
| Name |
|---|
Key |
ExperimentalDiffOperationAdd
Ƭ ExperimentalDiffOperationAdd<Key, Value>: Object
Type parameters
| Name | Type |
|---|---|
Key | Key |
Value | ReadonlyJSONValue |
Type declaration
| Name | Type |
|---|---|
key | Key |
newValue | Value |
op | "add" |
ExperimentalDiffOperationChange
Ƭ ExperimentalDiffOperationChange<Key, Value>: Object
Type parameters
| Name | Type |
|---|---|
Key | Key |
Value | ReadonlyJSONValue |
Type declaration
| Name | Type |
|---|---|
key | Key |
newValue | Value |
oldValue | Value |
op | "change" |
ExperimentalDiffOperationDel
Ƭ ExperimentalDiffOperationDel<Key, Value>: Object
Type parameters
| Name | Type |
|---|---|
Key | Key |
Value | ReadonlyJSONValue |
Type declaration
| Name | Type |
|---|---|
key | Key |
oldValue | Value |
op | "del" |
ExperimentalIndexDiff
Ƭ ExperimentalIndexDiff: readonly ExperimentalDiffOperation<IndexKey>[]
This type is experimental and may change in the future.
ExperimentalNoIndexDiff
Ƭ ExperimentalNoIndexDiff: readonly ExperimentalDiffOperation<string>[]
This type is experimental and may change in the future.
ExperimentalWatchCallbackForOptions
Ƭ ExperimentalWatchCallbackForOptions<Options>: Options extends ExperimentalWatchIndexOptions ? ExperimentalWatchIndexCallback : ExperimentalWatchNoIndexCallback
Type parameters
| Name | Type |
|---|---|
Options | extends ExperimentalWatchOptions |
ExperimentalWatchIndexCallback
Ƭ ExperimentalWatchIndexCallback: (diff: ExperimentalIndexDiff) => void
Type declaration
▸ (diff): void
Function that gets passed into experimentalWatch when doing a watch on a secondary index map and gets called when the data in Replicache changes.
This type is experimental and may change in the future.
Parameters
| Name | Type |
|---|---|
diff | ExperimentalIndexDiff |
Returns
void
ExperimentalWatchIndexOptions
Ƭ ExperimentalWatchIndexOptions: ExperimentalWatchNoIndexOptions & { indexName: string }
Options object passed to experimentalWatch. This is for an index watch.
ExperimentalWatchNoIndexCallback
Ƭ ExperimentalWatchNoIndexCallback: (diff: ExperimentalNoIndexDiff) => void
Type declaration
▸ (diff): void
Function that gets passed into experimentalWatch and gets called when the data in Replicache changes.
This type is experimental and may change in the future.
Parameters
| Name | Type |
|---|---|
diff | ExperimentalNoIndexDiff |
Returns
void
ExperimentalWatchNoIndexOptions
Ƭ ExperimentalWatchNoIndexOptions: Object
Options object passed to experimentalWatch. This is for a non index watch.
Type declaration
| Name | Type | Description |
|---|---|---|
initialValuesInFirstDiff? | boolean | When this is set to true (default is false), the watch callback will be called once asynchronously when watch is called. The arguments in that case is a diff where we consider all the existing values in Replicache as being added. |
prefix? | string | When provided, the watch is limited to changes where the key starts with prefix. |
ExperimentalWatchOptions
Ƭ ExperimentalWatchOptions: ExperimentalWatchIndexOptions | ExperimentalWatchNoIndexOptions
Options for experimentalWatch.
This interface is experimental and may change in the future.
GetIndexScanIterator
Ƭ GetIndexScanIterator: (indexName: string, fromSecondaryKey: string, fromPrimaryKey: string | undefined) => IterableUnion<readonly [key: IndexKey, value: ReadonlyJSONValue]>
Type declaration
▸ (indexName, fromSecondaryKey, fromPrimaryKey): IterableUnion<readonly [key: IndexKey, value: ReadonlyJSONValue]>
When using makeScanResult this is the type used for the function called when doing a scan with an
indexName.
Parameters
| Name | Type | Description |
|---|---|---|
indexName | string | The name of the index we are scanning over. |
fromSecondaryKey | string | The fromSecondaryKey is computed by scan and is the secondary key of the first entry to return in the iterator. It is based on prefix and start.key of the ScanIndexOptions. |
fromPrimaryKey | string | undefined | The fromPrimaryKey is computed by scan and is the primary key of the first entry to return in the iterator. It is based on prefix and start.key of the ScanIndexOptions. |
Returns
IterableUnion<readonly [key: IndexKey, value: ReadonlyJSONValue]>
GetScanIterator
Ƭ GetScanIterator: (fromKey: string) => IterableUnion<Entry<ReadonlyJSONValue>>
Type declaration
▸ (fromKey): IterableUnion<Entry<ReadonlyJSONValue>>
This is called when doing a scan without an
indexName.
Parameters
| Name | Type | Description |
|---|---|---|
fromKey | string | The fromKey is computed by scan and is the key of the first entry to return in the iterator. It is based on prefix and start.key of the ScanNoIndexOptions. |
Returns
IterableUnion<Entry<ReadonlyJSONValue>>
HTTPRequestInfo
Ƭ HTTPRequestInfo: Object
Type declaration
| Name | Type |
|---|---|
errorMessage | string |
httpStatusCode | number |
IndexDefinition
Ƭ IndexDefinition: Object
The definition of a single index.
Type declaration
| Name | Type | Description |
|---|---|---|
allowEmpty? | boolean | If true, indexing empty values will not emit a warning. Defaults to false. |
jsonPointer | string | A JSON Pointer pointing at the sub value inside each value to index over. For example, one might index over users' ages like so: {prefix: '/user/', jsonPointer: '/age'} |
prefix? | string | The prefix, if any, to limit the index over. If not provided the values of all keys are indexed. |
IndexDefinitions
Ƭ IndexDefinitions: Object
An object as a map defining the indexes. The keys are the index names and the values are the index definitions.
Index signature
▪ [name: string]: IndexDefinition
IndexKey
Ƭ IndexKey: readonly [secondary: string, primary: string]
When using indexes the key is a tuple of the secondary key and the primary key.
IterableUnion
Ƭ IterableUnion<T>: AsyncIterable<T> | Iterable<T>
Type parameters
| Name |
|---|
T |
JSONObject
Ƭ JSONObject: Object
A JSON object. This is a map from strings to JSON values.
Index signature
▪ [key: string]: JSONValue
JSONValue
Ƭ JSONValue: null | string | boolean | number | JSONValue[] | JSONObject
The values that can be represented in JSON
KeyTypeForScanOptions
Ƭ KeyTypeForScanOptions<O>: O extends ScanIndexOptions ? IndexKey : string
If the options contains an indexName then the key type is a tuple of
secondary and primary.
Type parameters
| Name | Type |
|---|---|
O | extends ScanOptions |
LogLevel
Ƭ LogLevel: "error" | "info" | "debug"
The different log levels. This is used to determine how much logging to do.
'error' > 'info' > 'debug'... meaning 'error' has highest priority
and 'debug' lowest.
MaybePromise
Ƭ MaybePromise<T>: T | Promise<T>
Type parameters
| Name |
|---|
T |
Mutation
Ƭ Mutation: Object
Mutation describes a single mutation done on the client.
Type declaration
| Name | Type |
|---|---|
args | ReadonlyJSONValue |
id | number |
name | string |
timestamp | number |
MutatorDefs
Ƭ MutatorDefs: Object
The type used to describe the mutator definitions passed into Replicache constructor as part of the ReplicacheOptions.
See ReplicacheOptions mutators for more info.
Index signature
▪ [key: string]: (tx: WriteTransaction, args?: any) => MutatorReturn
PatchOperation
Ƭ PatchOperation: { key: string ; op: "put" ; value: ReadonlyJSONValue } | { key: string ; op: "del" } | { op: "clear" }
This type describes the patch field in a PullResponse and it is used to describe how to update the Replicache key-value store.
PendingMutation
Ƭ PendingMutation: Object
Type declaration
| Name | Type |
|---|---|
args | ReadonlyJSONValue |
id | number |
name | string |
Poke
Ƭ Poke: Object
Type declaration
| Name | Type |
|---|---|
baseCookie | ReadonlyJSONValue |
pullResponse | PullResponse |
PullRequest
Ƭ PullRequest: Object
The JSON value used as the body when doing a POST to the pull endpoint.
Type declaration
| Name | Type |
|---|---|
clientID | ClientID |
cookie | ReadonlyJSONValue |
lastMutationID | number |
profileID | string |
pullVersion | number |
schemaVersion | string |
PullResponse
Ƭ PullResponse: PullResponseOK | ClientStateNotFoundResponse
PullResponse defines the shape and type of the response of a pull. This is the JSON you should return from your pull server endpoint.
PullResponseOK
Ƭ PullResponseOK: Object
The shape of a pull response under normal circumstances.
Type declaration
| Name | Type |
|---|---|
cookie? | ReadonlyJSONValue |
lastMutationID | number |
patch | PatchOperation[] |
Puller
Ƭ Puller: (request: Request) => Promise<PullerResult>
Type declaration
▸ (request): Promise<PullerResult>
Puller is the function type used to do the fetch part of a pull. The request is a POST request where the body is JSON with the type PullRequest.
Parameters
| Name | Type |
|---|---|
request | Request |
Returns
Promise<PullerResult>
PullerResult
Ƭ PullerResult: Object
Type declaration
| Name | Type |
|---|---|
httpRequestInfo | HTTPRequestInfo |
response? | PullResponse |
PushRequest
Ƭ PushRequest: Object
The JSON value used as the body when doing a POST to the push endpoint.
Type declaration
| Name | Type | Description |
|---|---|---|
clientID | ClientID | - |
mutations | Mutation[] | - |
profileID | string | - |
pushVersion | number | - |
schemaVersion | string | schemaVersion can optionally be used to specify to the push endpoint version information about the mutators the app is using (e.g., format of mutator args). |
Pusher
Ƭ Pusher: (request: Request) => Promise<HTTPRequestInfo>
Type declaration
▸ (request): Promise<HTTPRequestInfo>
Pusher is the function type used to do the fetch part of a push. The request is a POST request where the body is JSON with the type PushRequest.
Parameters
| Name | Type |
|---|---|
request | Request |
Returns
Promise<HTTPRequestInfo>
ReadonlyJSONObject
Ƭ ReadonlyJSONObject: Object
Like JSONObject but deeply readonly
Index signature
▪ [key: string]: ReadonlyJSONValue
ReadonlyJSONValue
Ƭ ReadonlyJSONValue: null | string | boolean | number | ReadonlyArray<ReadonlyJSONValue> | ReadonlyJSONObject
Like JSONValue but deeply readonly
ScanIndexOptions
Ƭ ScanIndexOptions: Object
Options for scan when scanning over an index. When
scanning over and index you need to provide the indexName and the start
key is now a tuple consisting of secondary and primary key
Type declaration
| Name | Type | Description |
|---|---|---|
indexName | string | Do a scan over a named index. The indexName is the name of an index defined when creating the Replicache instance using indexes. |
limit? | number | Only include up to limit results. |
prefix? | string | Only include results starting with the secondary keys starting with prefix. |
start? | { exclusive?: boolean ; key: ScanOptionIndexedStartKey } | When provided the scan starts at this key. |
start.exclusive? | boolean | Whether the key is exclusive or inclusive. |
start.key | ScanOptionIndexedStartKey | - |
ScanNoIndexOptions
Ƭ ScanNoIndexOptions: Object
Options for scan when scanning over the entire key space.
Type declaration
| Name | Type | Description |
|---|---|---|
limit? | number | Only include up to limit results. |
prefix? | string | Only include keys starting with prefix. |
start? | { exclusive?: boolean ; key: string } | When provided the scan starts at this key. |
start.exclusive? | boolean | Whether the key is exclusive or inclusive. |
start.key | string | - |
ScanOptionIndexedStartKey
Ƭ ScanOptionIndexedStartKey: readonly [secondary: string, primary?: string | undefined] | string
The key to start scanning at.
If you are scanning the primary index (i.e., you did not specify
indexName), then pass a single string for this field, which is the key in
the primary index to scan at.
If you are scanning a secondary index (i.e., you specified indexName), then
use the tuple form. In that case, secondary is the secondary key to start
scanning at, and primary (if any) is the primary key to start scanning at.
ScanOptions
Ƭ ScanOptions: ScanIndexOptions | ScanNoIndexOptions
Options for scan
Variables
TEST_LICENSE_KEY
• Const TEST_LICENSE_KEY: "This key only good for automated testing"
consoleLogSink
• Const consoleLogSink: LogSink
An implementation of Logger that logs using console.log etc
version
• Const version: string = REPLICACHE_VERSION
The current version of Replicache.
Functions
deleteAllReplicacheData
▸ deleteAllReplicacheData(createKVStore?): Promise<{ dropped: string[] ; errors: unknown[] }>
Deletes all IndexedDB data associated with Replicache.
Returns an object with the names of the successfully dropped databases and any errors encountered while dropping.
Parameters
| Name | Type |
|---|---|
createKVStore | ExperimentalCreateKVStore |
Returns
Promise<{ dropped: string[] ; errors: unknown[] }>
filterAsyncIterable
▸ filterAsyncIterable<V>(iter, predicate): AsyncIterable<V>
Filters an async iterable.
This utility function is provided because it is useful when using makeScanResult. It can be used to filter out tombstones (delete entries) for example.
Type parameters
| Name |
|---|
V |
Parameters
| Name | Type |
|---|---|
iter | IterableUnion<V> |
predicate | (v: V) => boolean |
Returns
AsyncIterable<V>
isScanIndexOptions
▸ isScanIndexOptions(options): options is ScanIndexOptions
Type narrowing of ScanOptions.
Parameters
| Name | Type |
|---|---|
options | ScanOptions |
Returns
options is ScanIndexOptions
makeIDBName
▸ makeIDBName(name, schemaVersion?): string
Returns the name of the IDB database that will be used for a particular Replicache instance.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the Replicache instance (i.e., the name field of ReplicacheOptions). |
schemaVersion? | string | The schema version of the database (i.e., the schemaVersion field of ReplicacheOptions). |
Returns
string
makeScanResult
▸ makeScanResult<Options>(options, getScanIterator): ScanResult<KeyTypeForScanOptions<Options>>
A helper function that makes it easier to implement scan with a custom backend.
If you are implementing a custom backend and have an in memory pending async iterable we provide two helper functions to make it easier to merge these together. mergeAsyncIterables and filterAsyncIterable.
For example:
const scanResult = makeScanResult(
options,
options.indexName
? () => {
throw Error('not implemented');
}
: fromKey => {
const persisted: AsyncIterable<Entry<ReadonlyJSONValue>> = ...;
const pending: AsyncIterable<Entry<ReadonlyJSONValue | undefined>> = ...;
const iter = await mergeAsyncIterables(persisted, pending);
const filteredIter = await filterAsyncIterable(
iter,
entry => entry[1] !== undefined,
);
return filteredIter;
},
);
Type parameters
| Name | Type |
|---|---|
Options | extends ScanOptions |
Parameters
| Name | Type |
|---|---|
options | Options |
getScanIterator | Options extends ScanIndexOptions ? GetIndexScanIterator : GetScanIterator |
Returns
ScanResult<KeyTypeForScanOptions<Options>>
mergeAsyncIterables
▸ mergeAsyncIterables<A, B>(iterableBase, iterableOverlay, compare): AsyncIterable<A | B>
Merges an iterable on to another iterable.
The two iterables need to be ordered and the compare function is used to
compare two different elements.
If two elements are equal (compare returns 0) then the element from the
second iterable is picked.
This utility function is provided because it is useful when using makeScanResult. It can be used to merge an in memory pending async iterable on to a persistent async iterable for example.
Type parameters
| Name |
|---|
A |
B |
Parameters
| Name | Type |
|---|---|
iterableBase | IterableUnion<A> |
iterableOverlay | IterableUnion<B> |
compare | (a: A, b: B) => number |
Returns
AsyncIterable<A | B>