Latest
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238import type {LogLevel, LogSink} from '@rocicorp/logger';import type {Pusher} from './pusher';import type {Puller} from './puller';import type {MutatorDefs, RequestOptions} from './replicache';import type * as kv from './kv/mod';
/** * The options passed to [[Replicache]]. */
export interface ReplicacheOptions<MD extends MutatorDefs> { /** * This is the URL to the server endpoint dealing with the push updates. See * [Push Endpoint Reference](https://doc.replicache.dev/server-push) for more * details. * * If not provided, push requests will not be made unless a custom * [[ReplicacheOptions.pusher]] is provided. */ pushURL?: string;
/** * This is the authorization token used when doing a * [pull](https://doc.replicache.dev/server-pull#authorization) and * [push](https://doc.replicache.dev/server-push#authorization). */ auth?: string;
/** * This is the URL to the server endpoint dealing with pull. See [Pull * Endpoint Reference](https://doc.replicache.dev/server-pull) for more * details. * * If not provided, pull requests will not be made unless a custom * [[ReplicacheOptions.puller]] is provided. */ pullURL?: string;
/** * The name of the Replicache database. * * It is important to use user specific names so that if there are multiple * tabs open for different distinct users their data is kept separate. * * For efficiency and performance, a new [[Replicache]] instance will * initialize its state from the persisted state of an existing [[Replicache]] * instance with the same `name`, domain and browser profile. * * Mutations from one [[Replicache]] instance may be pushed using the * [[ReplicacheOptions.auth]], [[ReplicacheOptions.pushURL]], * [[ReplicacheOptions.pullURL]], [[ReplicacheOptions.pusher]], and * [[ReplicacheOptions.puller]] of another Replicache instance with the same * `name`, domain and browser profile. * * You can use multiple Replicache instances for the same user as long as the * names are unique. e.g. `name: `$userID:$roomID` */ name: string;
/** * The schema version of the data understood by this application. This enables * versioning of mutators (in the push direction) and the client view (in the * pull direction). */ schemaVersion?: string;
/** * The duration between each [[pull]]. Set this to `null` to prevent pulling * in the background. */ pullInterval?: number | null;
/** * The delay between when a change is made to Replicache and when Replicache * attempts to push that change. */ pushDelay?: number;
/** * Determines how much logging to do. When this is set to `'debug'`, * Replicache will also log `'info'` and `'error'` messages. When set to * `'info'` we log `'info'` and `'error'` but not `'debug'`. When set to * `'error'` we only log `'error'` messages. * Default is `'info'`. */ logLevel?: LogLevel;
/** * Enables custom handling of logs. * * By default logs are logged to the console. If you would like logs to be * sent elsewhere (e.g. to a cloud logging service like DataDog) you can * provide an array of [[LogSink]]s. Logs at or above * [[ReplicacheOptions.logLevel]] are sent to each of these [[LogSink]]s. * If you would still like logs to go to the console, include * [[consoleLogSink]] in the array. * * ```ts * logSinks: [consoleLogSink, myCloudLogSink], * ``` */ logSinks?: LogSink[];
/** * An object used as a map to define the *mutators*. These gets registered at * startup of [[Replicache]]. * * *Mutators* are used to make changes to the data. * * #### Example * * The registered *mutations* are reflected on the * [[Replicache.mutate|mutate]] property of the [[Replicache]] instance. * * ```ts * const rep = new Replicache({ * name: 'user-id', * mutators: { * async createTodo(tx: WriteTransaction, args: JSONValue) { * const key = `/todo/${args.id}`; * if (await tx.has(key)) { * throw new Error('Todo already exists'); * } * await tx.put(key, args); * }, * async deleteTodo(tx: WriteTransaction, id: number) { * ... * }, * }, * }); * ``` * * This will create the function to later use: * * ```ts * await rep.mutate.createTodo({ * id: 1234, * title: 'Make things work offline', * complete: true, * }); * ``` * * #### Replays * * *Mutators* run once when they are initially invoked, but they might also be * *replayed* multiple times during sync. As such *mutators* should not modify * application state directly. Also, it is important that the set of * registered mutator names only grows over time. If Replicache syncs and * needed *mutator* is not registered, it will substitute a no-op mutator, but * this might be a poor user experience. * * #### Server application * * During push, a description of each mutation is sent to the server's [push * endpoint](https://doc.replicache.dev/server-push) where it is applied. Once * the *mutation* has been applied successfully, as indicated by the client * view's * [`lastMutationId`](https://doc.replicache.dev/server-pull#lastmutationid) * field, the local version of the *mutation* is removed. See the [design * doc](https://doc.replicache.dev/design#commits) for additional details on * the sync protocol. * * #### Transactionality * * *Mutators* are atomic: all their changes are applied together, or none are. * Throwing an exception aborts the transaction. Otherwise, it is committed. * As with [[query]] and [[subscribe]] all reads will see a consistent view of * the cache while they run. */ mutators?: MD;
/** * Options to use when doing pull and push requests. */ requestOptions?: RequestOptions;
/** * Allows passing in a custom implementation of a [[Puller]] function. This * function is called when doing a pull and it is responsible for * communicating with the server. * * Normally, this is just a POST to a URL with a JSON body but you can provide * your own function if you need to do things differently. */ puller?: Puller;
/** * Allows passing in a custom implementation of a [[Pusher]] function. This * function is called when doing a push and it is responsible for * communicating with the server. * * Normally, this is just a POST to a URL with a JSON body but you can provide * your own function if you need to do things differently. */ pusher?: Pusher;
/** * The license key for Replicache. This parameter is required for Replicache to * function. See https://replicache.dev for how to acquire a license key. * * YOU SHOULD PASS TEST_LICENSE_KEY IN AUTOMATED TESTS. It disables license * checks for several minutes. If you pass a normal license key in tests, each test * that instantiates Replicache will attempt to perform a license check against * Replicache's licensing server, potentially increasing your monthly active browser * profile count, slowing the test down, and spamming Replicache's servers. */ licenseKey: string;
/** * Allows implementing the underlying storage layer completely in JavaScript. * * @experimental This option is experimental and might be removed or changed * in the future without following semver versioning. Please be cautious. */ experimentalKVStore?: kv.Store;}
export type ReplicacheInternalOptions = { /** * Defaults to true. */ enableLicensing?: boolean; /** * Defaults to true. */ enableMutationRecovery?: boolean;
/** * Allows exposing parts of the internal API to a subclass. This works when * thing have been minified and with the npm package. */ exposeInternalAPI?: (api: ReplicacheInternalAPI) => void;};
export interface ReplicacheInternalAPI { persist(): Promise<void>;}