Skip to main content

Class: Replicache<MD>

Type parameters

NameType
MDextends MutatorDefs = {}

Constructors

constructor

new Replicache<MD>(options)

Type parameters

NameType
MDextends MutatorDefs = {}

Parameters

NameType
optionsReplicacheOptions<MD>

Properties

auth

auth: string

The authorization token used when doing a push request.


getAuth

getAuth: undefined | null | () => MaybePromise<undefined | null | string> = null

This gets called when we get an HTTP unauthorized (401) response from the push or pull endpoint. Set this to a function that will ask your user to reauthenticate.


mutate

Readonly mutate: MakeMutators<MD>

The mutators that was registered in the constructor.


name

Readonly name: string

The name of the Replicache database.


onClientStateNotFound

onClientStateNotFound: null | (reason: ClientStateNotFoundReason) => void = reload

onClientStateNotFound is called when the persistent client has been garbage collected. This can happen if the client has not been used for over a week.

It can also happen if the server no longer knows about this client.

The default behavior is to reload the page (using location.reload()). Set this to null or provide your own function to prevent the page from reloading automatically.


onOnlineChange

onOnlineChange: null | (online: boolean) => void = null

onOnlineChange is called when the online property changes. See online for more details.


onSync

onSync: null | (syncing: boolean) => void = null

onSync is called when a sync begins, and again when the sync ends. The parameter syncing is set to true when onSync is called at the beginning of a sync, and false when it is called at the end of a sync.

This can be used in a React like app by doing something like the following:

const [syncing, setSyncing] = useState(false);
useEffect(() => {
rep.onSync = setSyncing;
}, [rep]);

pullInterval

pullInterval: null | number

The duration between each periodic pull. Setting this to null disables periodic pull completely. Pull will still happen if you call pull manually.


pullURL

pullURL: string

The URL to use when doing a pull request.


puller

puller: Puller

The function to use to pull data from the server.


pushDelay

pushDelay: number

The delay between when a change is made to Replicache and when Replicache attempts to push that change.


pushURL

pushURL: string

The URL to use when doing a push request.


pusher

pusher: Pusher

The function to use to push data to the server.


schemaVersion

Readonly schemaVersion: string

The schema version of the data understood by this application.

Accessors

clientID

get clientID(): Promise<string>

The client ID for this instance of Replicache. Each instance of Replicache gets a unique client ID.

Returns

Promise<string>


closed

get closed(): boolean

Whether the Replicache database has been closed. Once Replicache has been closed it no longer syncs and you can no longer read or write data out of it. After it has been closed it is pretty much useless and should not be used any more.

Returns

boolean


idbName

get idbName(): string

This is the name Replicache uses for the IndexedDB database where data is stored.

Returns

string


online

get online(): boolean

A rough heuristic for whether the client is currently online. Note that there is no way to know for certain whether a client is online - the next request can always fail. This property returns true if the last sync attempt succeeded, and false otherwise.

Returns

boolean


profileID

get profileID(): Promise<string>

The browser profile ID for this browser profile. Every instance of Replicache browser-profile-wide shares the same profile ID.

Returns

Promise<string>


requestOptions

get requestOptions(): Required<RequestOptions>

The options used to control the pull and push request behavior. This object is live so changes to it will affect the next pull or push call.

Returns

Required<RequestOptions>

Methods

close

close(): Promise<void>

Closes this Replicache instance.

When closed all subscriptions end and no more read or writes are allowed.

Returns

Promise<void>


createIndex

createIndex(def): Promise<void>

Creates a persistent secondary index in Replicache which can be used with scan.

If the named index already exists with the same definition this returns success immediately. If the named index already exists, but with a different definition an error is thrown.

Parameters

NameType
defCreateIndexDefinition

Returns

Promise<void>


dropIndex

dropIndex(name): Promise<void>

Drops an index previously created with createIndex.

Parameters

NameType
namestring

Returns

Promise<void>


experimentalWatch

experimentalWatch(callback, options?): () => void

Watches Replicache for changes.

The callback gets called whenever the underlying data changes and the key changes matches the [[WatchOptions.prefix]] if present. If a change occurs to the data but the change does not impact the key space the callback is not called. In other words, the callback is never called with an empty diff.

This gets called after commit (a mutation or a rebase).

experimental This method is under development and its semantics will change.

Parameters

NameType
callbackExperimentalWatchCallback
options?ExperimentalWatchOptions

Returns

fn

▸ (): void

Watches Replicache for changes.

The callback gets called whenever the underlying data changes and the key changes matches the [[WatchOptions.prefix]] if present. If a change occurs to the data but the change does not impact the key space the callback is not called. In other words, the callback is never called with an empty diff.

This gets called after commit (a mutation or a rebase).

experimental This method is under development and its semantics will change.

Returns

void


poke

poke(poke): Promise<void>

Applies an update from the server to Replicache. Throws an error if cookie does not match. In that case the server thinks this client has a different cookie than it does; the caller should disconnect from the server and re-register, which transmits the cookie the client actually has.

experimental This method is under development and its semantics will change.

Parameters

NameType
pokePoke

Returns

Promise<void>


pull

pull(): void

Pull pulls changes from the pullURL. If there are any changes local changes will get replayed on top of the new server state.

Returns

void


query

query<R>(body): Promise<R>

Query is used for read transactions. It is recommended to use transactions to ensure you get a consistent view across multiple calls to get, has and scan.

Type parameters

Name
R

Parameters

NameType
body(tx: ReadTransaction) => R | Promise<R>

Returns

Promise<R>


subscribe

subscribe<R, E>(body, options): () => void

Subscribe to changes to the underlying data. Every time the underlying data changes body is called and if the result of body changes compared to last time onData is called. The function is also called once the first time the subscription is added.

This returns a function that can be used to cancel the subscription.

If an error occurs in the body the onError function is called if present. Otherwise, the error is thrown.

Type parameters

NameType
Rextends undefined | ReadonlyJSONValue
EE

Parameters

NameType
body(tx: ReadTransaction) => Promise<R>
optionsSubscribeOptions<R, E>

Returns

fn

▸ (): void

Subscribe to changes to the underlying data. Every time the underlying data changes body is called and if the result of body changes compared to last time onData is called. The function is also called once the first time the subscription is added.

This returns a function that can be used to cancel the subscription.

If an error occurs in the body the onError function is called if present. Otherwise, the error is thrown.

Returns

void