packages/store/api-report.api.md
Do not edit this file. It is a report generated by API Extractor.
import { Atom } from '@tldraw/state';
import { Computed } from '@tldraw/state';
import { Expand } from '@tldraw/utils';
import { Result } from '@tldraw/utils';
import { Signal } from '@tldraw/state';
import { UNINITIALIZED } from '@tldraw/state';
// @public
export function assertIdType<R extends UnknownRecord>(id: string | undefined, type: RecordType<R, any>): asserts id is IdOf<R>;
// @public
export class AtomMap<K, V> implements Map<K, V> {
[Symbol.iterator](): Generator<[K, V], undefined, unknown>;
[Symbol.toStringTag]: string;
constructor(name: string, entries?: Iterable<readonly [K, V]>);
__unsafe__getWithoutCapture(key: K): undefined | V;
__unsafe__hasWithoutCapture(key: K): boolean;
clear(): void;
delete(key: K): boolean;
deleteMany(keys: Iterable<K>): [K, V][];
entries(): Generator<[K, V], undefined, unknown>;
forEach(callbackfn: (value: V, key: K, map: AtomMap<K, V>) => void, thisArg?: any): void;
get(key: K): undefined | V;
// @internal
getAtom(key: K): Atom<UNINITIALIZED | V> | undefined;
has(key: K): boolean;
keys(): Generator<K, undefined, unknown>;
set(key: K, value: V): this;
get size(): number;
update(key: K, updater: (value: V) => V): void;
values(): Generator<V, undefined, unknown>;
}
// @public
export class AtomSet<T> {
// (undocumented)
[Symbol.iterator](): Generator<T, undefined, unknown>;
// (undocumented)
[Symbol.toStringTag]: string;
constructor(name: string, keys?: Iterable<T>);
// (undocumented)
add(value: T): this;
// (undocumented)
clear(): void;
// (undocumented)
delete(value: T): boolean;
// (undocumented)
entries(): Generator<[T, T], undefined, unknown>;
// (undocumented)
forEach(callbackfn: (value: T, value2: T, set: AtomSet<T>) => void, thisArg?: any): void;
// (undocumented)
has(value: T): boolean;
// (undocumented)
keys(): Generator<T, undefined, unknown>;
// (undocumented)
get size(): number;
// (undocumented)
values(): Generator<T, undefined, unknown>;
}
// @public
export interface BaseRecord<TypeName extends string, Id extends RecordId<UnknownRecord>> {
// (undocumented)
readonly id: Id;
// (undocumented)
readonly typeName: TypeName;
}
// @public
export type ChangeSource = 'remote' | 'user';
// @public
export interface CollectionDiff<T> {
added?: Set<T>;
removed?: Set<T>;
}
// @public
export interface ComputedCache<Data, R extends UnknownRecord> {
get(id: IdOf<R>): Data | undefined;
}
// @public
export function createComputedCache<Context extends StoreObject<any>, Result, Record extends StoreObjectRecordType<Context> = StoreObjectRecordType<Context>>(name: string, derive: (context: Context, record: Record) => Result | undefined, opts?: CreateComputedCacheOpts<Result, Record>): {
get(context: Context, id: IdOf<Record>): Result | undefined;
};
// @public
export interface CreateComputedCacheOpts<Data, R extends UnknownRecord> {
areRecordsEqual?(a: R, b: R): boolean;
areResultsEqual?(a: Data, b: Data): boolean;
}
// @internal
export function createEmptyRecordsDiff<R extends UnknownRecord>(): RecordsDiff<R>;
// @public
export function createMigrationIds<const ID extends string, const Versions extends Record<string, number>>(sequenceId: ID, versions: Versions): {
[K in keyof Versions]: `${ID}/${Versions[K]}`;
};
// @public
export function createMigrationSequence({ sequence, sequenceId, retroactive }: {
retroactive?: boolean;
sequence: Array<Migration | StandaloneDependsOn>;
sequenceId: string;
}): MigrationSequence;
// @internal
export function createRecordMigrationSequence(opts: {
filter?(record: UnknownRecord): boolean;
recordType: string;
retroactive?: boolean;
sequence: Omit<Extract<Migration, {
scope: 'record';
}>, 'scope'>[];
sequenceId: string;
}): MigrationSequence;
// @public
export function createRecordType<R extends UnknownRecord>(typeName: R['typeName'], config: {
ephemeralKeys?: {
readonly [K in Exclude<keyof R, 'id' | 'typeName'>]: boolean;
};
scope: RecordScope;
validator?: StoreValidator<R>;
}): RecordType<R, keyof Omit<R, 'id' | 'typeName'>>;
// @public
export function devFreeze<T>(object: T): T;
// @public
export interface HistoryEntry<R extends UnknownRecord = UnknownRecord> {
changes: RecordsDiff<R>;
source: ChangeSource;
}
// @public
export type IdOf<R extends UnknownRecord> = R['id'];
// @internal
export class IncrementalSetConstructor<T> {
constructor(
previousValue: Set<T>);
// @public
add(item: T): void;
// @public
get(): {
diff: CollectionDiff<T>;
value: Set<T>;
} | undefined;
// @public
remove(item: T): void;
}
// @public
export function isRecordsDiffEmpty<T extends UnknownRecord>(diff: RecordsDiff<T>): boolean;
// @public
export interface LegacyBaseMigrationsInfo {
// (undocumented)
currentVersion: number;
// (undocumented)
firstVersion: number;
// (undocumented)
migrators: {
[version: number]: LegacyMigration;
};
}
// @public
export interface LegacyMigration<Before = any, After = any> {
// (undocumented)
down: (newState: After) => Before;
// (undocumented)
up: (oldState: Before) => After;
}
// @public
export interface LegacyMigrations extends LegacyBaseMigrationsInfo {
// (undocumented)
subTypeKey?: string;
// (undocumented)
subTypeMigrations?: Record<string, LegacyBaseMigrationsInfo>;
}
// @public
export type Migration = {
readonly dependsOn?: readonly MigrationId[] | undefined;
readonly id: MigrationId;
} & ({
readonly down?: (newState: SerializedStore<UnknownRecord>) => SerializedStore<UnknownRecord> | void;
readonly scope: 'store';
readonly up: (oldState: SerializedStore<UnknownRecord>) => SerializedStore<UnknownRecord> | void;
} | {
readonly down?: (newState: UnknownRecord) => UnknownRecord | void;
readonly filter?: (record: UnknownRecord) => boolean;
readonly scope: 'record';
readonly up: (oldState: UnknownRecord) => UnknownRecord | void;
} | {
readonly down?: never;
readonly scope: 'storage';
readonly up: (storage: SynchronousRecordStorage<UnknownRecord>) => void;
});
// @public (undocumented)
export const MigrationFailureReason: {
readonly IncompatibleSubtype: "incompatible-subtype";
readonly MigrationError: "migration-error";
readonly TargetVersionTooNew: "target-version-too-new";
readonly TargetVersionTooOld: "target-version-too-old";
readonly UnknownType: "unknown-type";
readonly UnrecognizedSubtype: "unrecognized-subtype";
};
// @public (undocumented)
export type MigrationFailureReason = (typeof MigrationFailureReason)[keyof typeof MigrationFailureReason];
// @public (undocumented)
export namespace MigrationFailureReason {
// (undocumented)
export type IncompatibleSubtype = typeof MigrationFailureReason.IncompatibleSubtype;
// (undocumented)
export type MigrationError = typeof MigrationFailureReason.MigrationError;
// (undocumented)
export type TargetVersionTooNew = typeof MigrationFailureReason.TargetVersionTooNew;
// (undocumented)
export type TargetVersionTooOld = typeof MigrationFailureReason.TargetVersionTooOld;
// (undocumented)
export type UnknownType = typeof MigrationFailureReason.UnknownType;
// (undocumented)
export type UnrecognizedSubtype = typeof MigrationFailureReason.UnrecognizedSubtype;
}
// @public
export type MigrationId = `${string}/${number}`;
// @public
export type MigrationResult<T> = {
reason: MigrationFailureReason;
type: 'error';
} | {
type: 'success';
value: T;
};
// @public
export interface MigrationSequence {
retroactive: boolean;
// (undocumented)
sequence: Migration[];
// (undocumented)
sequenceId: string;
}
// @internal
export function parseMigrationId(id: MigrationId): {
sequenceId: string;
version: number;
};
// @public (undocumented)
export type QueryExpression<R extends object> = {
[k in keyof R & string]?: R[k] extends boolean | null | number | string | undefined ? QueryValueMatcher<R[k]> : R[k] extends object ? QueryExpression<R[k]> : QueryValueMatcher<R[k]>;
};
// @public
export type QueryValueMatcher<T> = {
eq: T;
} | {
gt: number;
} | {
neq: T;
};
// @public
export type RecordFromId<K extends RecordId<UnknownRecord>> = K extends RecordId<infer R> ? R : never;
// @public
export type RecordId<R extends UnknownRecord> = string & {
__type__: R;
};
// @public
export type RecordScope = 'document' | 'presence' | 'session';
// @public
export interface RecordsDiff<R extends UnknownRecord> {
added: Record<IdOf<R>, R>;
removed: Record<IdOf<R>, R>;
updated: Record<IdOf<R>, [from: R, to: R]>;
}
// @public
export class RecordType<R extends UnknownRecord, RequiredProperties extends keyof Omit<R, 'id' | 'typeName'>> {
constructor(
typeName: R['typeName'], config: {
readonly createDefaultProperties: () => Exclude<Omit<R, 'id' | 'typeName'>, RequiredProperties>;
readonly ephemeralKeys?: {
readonly [K in Exclude<keyof R, 'id' | 'typeName'>]: boolean;
};
readonly scope?: RecordScope;
readonly validator?: StoreValidator<R>;
});
clone(record: R): R;
create(properties: Expand<Pick<R, RequiredProperties> & Omit<Partial<R>, RequiredProperties>>): R;
readonly createDefaultProperties: () => Exclude<Omit<R, 'id' | 'typeName'>, RequiredProperties>;
createId(customUniquePart?: string): IdOf<R>;
readonly ephemeralKeys?: {
readonly [K in Exclude<keyof R, 'id' | 'typeName'>]: boolean;
};
readonly ephemeralKeySet: ReadonlySet<string>;
isId(id?: string): id is IdOf<R>;
isInstance(record?: UnknownRecord): record is R;
parseId(id: IdOf<R>): string;
readonly scope: RecordScope;
readonly typeName: R['typeName'];
validate(record: unknown, recordBefore?: R): R;
readonly validator: StoreValidator<R>;
withDefaultProperties<DefaultProps extends Omit<Partial<R>, 'id' | 'typeName'>>(createDefaultProperties: () => DefaultProps): RecordType<R, Exclude<RequiredProperties, keyof DefaultProps>>;
}
// @public
export function reverseRecordsDiff(diff: RecordsDiff<any>): RecordsDiff<any>;
// @public
export type RSIndex<R extends UnknownRecord> = Computed<RSIndexMap<R>, RSIndexDiff<R>>;
// @public
export type RSIndexDiff<R extends UnknownRecord> = Map<any, CollectionDiff<IdOf<R>>>;
// @public
export type RSIndexMap<R extends UnknownRecord> = Map<any, Set<IdOf<R>>>;
// @public
export type SerializedSchema = SerializedSchemaV1 | SerializedSchemaV2;
// @public
export interface SerializedSchemaV1 {
recordVersions: Record<string, {
subTypeKey: string;
subTypeVersions: Record<string, number>;
version: number;
} | {
version: number;
}>;
schemaVersion: 1;
storeVersion: number;
}
// @public
export interface SerializedSchemaV2 {
// (undocumented)
schemaVersion: 2;
// (undocumented)
sequences: {
[sequenceId: string]: number;
};
}
// @public
export type SerializedStore<R extends UnknownRecord> = Record<IdOf<R>, R>;
// @public
export function squashRecordDiffs<T extends UnknownRecord>(diffs: RecordsDiff<T>[], options?: {
mutateFirstDiff?: boolean;
}): RecordsDiff<T>;
// @internal
export function squashRecordDiffsMutable<T extends UnknownRecord>(target: RecordsDiff<T>, diffs: RecordsDiff<T>[]): void;
// @public
export interface StandaloneDependsOn {
// (undocumented)
readonly dependsOn: readonly MigrationId[];
}
// @public
export class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
constructor(config: {
props: Props;
id?: string;
schema: StoreSchema<R, Props>;
initialData?: SerializedStore<R>;
});
// @internal (undocumented)
addHistoryInterceptor(fn: (entry: HistoryEntry<R>, source: ChangeSource) => void): () => void;
allRecords(): R[];
// (undocumented)
applyDiff(diff: RecordsDiff<R>, { runCallbacks, ignoreEphemeralKeys }?: {
ignoreEphemeralKeys?: boolean;
runCallbacks?: boolean;
}): void;
// @internal (undocumented)
atomic<T>(fn: () => T, runCallbacks?: boolean, isMergingRemoteChanges?: boolean): T;
clear(): void;
createCache<Result, Record extends R = R>(create: (id: IdOf<Record>, recordSignal: Signal<R>) => Signal<Result>): {
get: (id: IdOf<Record>) => Result | undefined;
};
createComputedCache<Result, Record extends R = R>(name: string, derive: (record: Record) => Result | undefined, opts?: CreateComputedCacheOpts<Result, Record>): ComputedCache<Result, Record>;
// (undocumented)
dispose(): void;
// @internal (undocumented)
ensureStoreIsUsable(): void;
extractingChanges(fn: () => void): RecordsDiff<R>;
filterChangesByScope(change: RecordsDiff<R>, scope: RecordScope): {
added: { [K in IdOf<R>]: R; };
removed: { [K in IdOf<R>]: R; };
updated: { [K in IdOf<R>]: [from: R, to: R]; };
} | null;
// (undocumented)
_flushHistory(): void;
get<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined;
getStoreSnapshot(scope?: 'all' | RecordScope): StoreSnapshot<R>;
has<K extends IdOf<R>>(id: K): boolean;
readonly history: Atom<number, RecordsDiff<R>>;
readonly id: string;
// @internal (undocumented)
isPossiblyCorrupted(): boolean;
listen(onHistory: StoreListener<R>, filters?: Partial<StoreListenerFilters>): () => void;
loadStoreSnapshot(snapshot: StoreSnapshot<R>): void;
// @internal (undocumented)
markAsPossiblyCorrupted(): void;
mergeRemoteChanges(fn: () => void): void;
migrateSnapshot(snapshot: StoreSnapshot<R>): StoreSnapshot<R>;
readonly props: Props;
put(records: R[], phaseOverride?: 'initialize'): void;
readonly query: StoreQueries<R>;
remove(ids: IdOf<R>[]): void;
readonly schema: StoreSchema<R, Props>;
readonly scopedTypes: {
readonly [K in RecordScope]: ReadonlySet<R['typeName']>;
};
serialize(scope?: 'all' | RecordScope): SerializedStore<R>;
readonly sideEffects: StoreSideEffects<R>;
unsafeGetWithoutCapture<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined;
update<K extends IdOf<R>>(id: K, updater: (record: RecordFromId<K>) => RecordFromId<K>): void;
// (undocumented)
validate(phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord'): void;
}
// @public
export type StoreAfterChangeHandler<R extends UnknownRecord> = (prev: R, next: R, source: 'remote' | 'user') => void;
// @public
export type StoreAfterCreateHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => void;
// @public
export type StoreAfterDeleteHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => void;
// @public
export type StoreBeforeChangeHandler<R extends UnknownRecord> = (prev: R, next: R, source: 'remote' | 'user') => R;
// @public
export type StoreBeforeCreateHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => R;
// @public
export type StoreBeforeDeleteHandler<R extends UnknownRecord> = (record: R, source: 'remote' | 'user') => false | void;
// @public
export interface StoreError {
error: Error;
isExistingValidationIssue: boolean;
phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord';
recordAfter: unknown;
recordBefore?: unknown;
}
// @public
export type StoreListener<R extends UnknownRecord> = (entry: HistoryEntry<R>) => void;
// @public
export interface StoreListenerFilters {
scope: 'all' | RecordScope;
source: 'all' | ChangeSource;
}
// @public
export type StoreObject<R extends UnknownRecord> = {
store: Store<R>;
} | Store<R>;
// @public
export type StoreObjectRecordType<Context extends StoreObject<any>> = Context extends Store<infer R> ? R : Context extends {
store: Store<infer R>;
} ? R : never;
// @public
export type StoreOperationCompleteHandler = (source: 'remote' | 'user') => void;
// @public
export class StoreQueries<R extends UnknownRecord> {
// @internal
constructor(recordMap: AtomMap<IdOf<R>, R>, history: Atom<number, RecordsDiff<R>>);
// @internal
__uncached_createIndex<TypeName extends R['typeName']>(typeName: TypeName, path: string): RSIndex<Extract<R, {
typeName: TypeName;
}>>;
exec<TypeName extends R['typeName']>(typeName: TypeName, query: QueryExpression<Extract<R, {
typeName: TypeName;
}>>): Array<Extract<R, {
typeName: TypeName;
}>>;
filterHistory<TypeName extends R['typeName']>(typeName: TypeName): Computed<number, RecordsDiff<Extract<R, {
typeName: TypeName;
}>>>;
// @internal (undocumented)
getAllIdsForType<TypeName extends R['typeName']>(typeName: TypeName): Set<IdOf<Extract<R, {
typeName: TypeName;
}>>>;
// @internal (undocumented)
getRecordById<TypeName extends R['typeName']>(typeName: TypeName, id: IdOf<Extract<R, {
typeName: TypeName;
}>>): Extract<R, {
typeName: TypeName;
}> | undefined;
ids<TypeName extends R['typeName']>(typeName: TypeName, queryCreator?: () => QueryExpression<Extract<R, {
typeName: TypeName;
}>>, name?: string): Computed<Set<IdOf<Extract<R, {
typeName: TypeName;
}>>>, CollectionDiff<IdOf<Extract<R, {
typeName: TypeName;
}>>>>;
index<TypeName extends R['typeName']>(typeName: TypeName, path: string): RSIndex<Extract<R, {
typeName: TypeName;
}>>;
record<TypeName extends R['typeName']>(typeName: TypeName, queryCreator?: () => QueryExpression<Extract<R, {
typeName: TypeName;
}>>, name?: string): Computed<Extract<R, {
typeName: TypeName;
}> | undefined>;
records<TypeName extends R['typeName']>(typeName: TypeName, queryCreator?: () => QueryExpression<Extract<R, {
typeName: TypeName;
}>>, name?: string): Computed<Array<Extract<R, {
typeName: TypeName;
}>>>;
}
// @internal
export type StoreRecord<S extends Store<any>> = S extends Store<infer R> ? R : never;
// @public
export class StoreSchema<R extends UnknownRecord, P = unknown> {
static create<R extends UnknownRecord, P = unknown>(types: {
[TypeName in R['typeName']]: {
createId: any;
};
}, options?: StoreSchemaOptions<R, P>): StoreSchema<R, P>;
// @internal
createIntegrityChecker(store: Store<R, P>): (() => void) | undefined;
getMigrationsSince(persistedSchema: SerializedSchema): Result<Migration[], string>;
// @internal
getType(typeName: string): RecordType<R, any>;
migratePersistedRecord(record: R, persistedSchema: SerializedSchema, direction?: 'down' | 'up'): MigrationResult<R>;
// (undocumented)
migrateStorage(storage: SynchronousStorage<R>): void;
migrateStoreSnapshot(snapshot: StoreSnapshot<R>, opts?: {
mutateInputStore?: boolean;
}): MigrationResult<SerializedStore<R>>;
// (undocumented)
readonly migrations: Record<string, MigrationSequence>;
serialize(): SerializedSchemaV2;
// @internal @deprecated
serializeEarliestVersion(): SerializedSchema;
// (undocumented)
readonly sortedMigrations: readonly Migration[];
// (undocumented)
readonly types: {
[Record in R as Record['typeName']]: RecordType<R, any>;
};
validateRecord(store: Store<R>, record: R, phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord', recordBefore: null | R): R;
}
// @public
export interface StoreSchemaOptions<R extends UnknownRecord, P> {
// @internal (undocumented)
createIntegrityChecker?(store: Store<R, P>): void;
// (undocumented)
migrations?: MigrationSequence[];
// (undocumented)
onValidationFailure?(data: StoreValidationFailure<R>): R;
}
// @public
export class StoreSideEffects<R extends UnknownRecord> {
constructor(store: Store<R>);
// @internal
handleAfterChange(prev: R, next: R, source: 'remote' | 'user'): void;
// @internal
handleAfterCreate(record: R, source: 'remote' | 'user'): void;
// @internal
handleAfterDelete(record: R, source: 'remote' | 'user'): void;
// @internal
handleBeforeChange(prev: R, next: R, source: 'remote' | 'user'): R;
// @internal
handleBeforeCreate(record: R, source: 'remote' | 'user'): R;
// @internal
handleBeforeDelete(record: R, source: 'remote' | 'user'): boolean;
// @internal
handleOperationComplete(source: 'remote' | 'user'): void;
// @internal
isEnabled(): boolean;
// @internal
register(handlersByType: {
[T in R as T['typeName']]?: {
afterChange?: StoreAfterChangeHandler<T>;
afterCreate?: StoreAfterCreateHandler<T>;
afterDelete?: StoreAfterDeleteHandler<T>;
beforeChange?: StoreBeforeChangeHandler<T>;
beforeCreate?: StoreBeforeCreateHandler<T>;
beforeDelete?: StoreBeforeDeleteHandler<T>;
};
}): () => void;
registerAfterChangeHandler<T extends R['typeName']>(typeName: T, handler: StoreAfterChangeHandler<R & {
typeName: T;
}>): () => void;
registerAfterCreateHandler<T extends R['typeName']>(typeName: T, handler: StoreAfterCreateHandler<R & {
typeName: T;
}>): () => void;
registerAfterDeleteHandler<T extends R['typeName']>(typeName: T, handler: StoreAfterDeleteHandler<R & {
typeName: T;
}>): () => void;
registerBeforeChangeHandler<T extends R['typeName']>(typeName: T, handler: StoreBeforeChangeHandler<R & {
typeName: T;
}>): () => void;
registerBeforeCreateHandler<T extends R['typeName']>(typeName: T, handler: StoreBeforeCreateHandler<R & {
typeName: T;
}>): () => void;
registerBeforeDeleteHandler<T extends R['typeName']>(typeName: T, handler: StoreBeforeDeleteHandler<R & {
typeName: T;
}>): () => void;
registerOperationCompleteHandler(handler: StoreOperationCompleteHandler): () => void;
// @internal
setIsEnabled(enabled: boolean): void;
}
// @public
export interface StoreSnapshot<R extends UnknownRecord> {
schema: SerializedSchema;
store: SerializedStore<R>;
}
// @public
export interface StoreValidationFailure<R extends UnknownRecord> {
// (undocumented)
error: unknown;
// (undocumented)
phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord';
// (undocumented)
record: R;
// (undocumented)
recordBefore: null | R;
// (undocumented)
store: Store<R>;
}
// @public
export interface StoreValidator<R extends UnknownRecord> {
validate(record: unknown): R;
validateUsingKnownGoodVersion?(knownGoodVersion: R, record: unknown): R;
}
// @public
export type StoreValidators<R extends UnknownRecord> = {
[K in R['typeName']]: StoreValidator<Extract<R, {
typeName: K;
}>>;
};
// @public
export interface SynchronousRecordStorage<R extends UnknownRecord> {
// (undocumented)
delete(id: string): void;
// (undocumented)
entries(): Iterable<[string, R]>;
// (undocumented)
get(id: string): R | undefined;
// (undocumented)
keys(): Iterable<string>;
// (undocumented)
set(id: string, record: R): void;
// (undocumented)
values(): Iterable<R>;
}
// @public
export interface SynchronousStorage<R extends UnknownRecord> extends SynchronousRecordStorage<R> {
// (undocumented)
getSchema(): SerializedSchema;
// (undocumented)
setSchema(schema: SerializedSchema): void;
}
// @public
export type UnknownRecord = BaseRecord<string, RecordId<UnknownRecord>>;
// (No @packageDocumentation comment for this package)