@verdant-web/store 2.8.5 → 3.0.0

package/dist/cjs/entities/Entity.d.ts

@@ -1,134 +1,101 @@
-import { EventSubscriber, FileData, ObjectIdentifier, Operation, PatchCreator, StorageFieldSchema, StorageFieldsSchema, TimestampProvider } from '@verdant-web/common';
-import { EntityFile } from '../files/EntityFile.js';
-export declare const ADD_OPERATIONS = "@@addOperations";
-export declare const DELETE = "@@delete";
-export declare const REBASE = "@@rebase";
-declare const REFRESH = "@@refresh";
-export declare const DEEP_CHANGE = "@@deepChange";
-export interface CacheTools {
-    computeView(oid: ObjectIdentifier): {
-        view: any;
-        deleted: boolean;
-        lastTimestamp: number | null;
-    };
-    getEntity(params: {
-        oid: ObjectIdentifier;
-        fieldSchema: StorageFieldSchema;
-        parent?: Entity;
-        fieldKey?: string | number;
-    }): Entity;
-    hasOid(oid: ObjectIdentifier): boolean;
-    weakRef<T extends object>(value: T): WeakRef<T>;
-}
-export interface StoreTools {
-    addLocalOperations(operations: Operation[]): void;
+import { EntityValidationProblem, EventSubscriber, ObjectIdentifier, PatchCreator, StorageFieldSchema } from '@verdant-web/common';
+import { Context } from '../context.js';
+import { FileManager } from '../files/FileManager.js';
+import { EntityCache } from './EntityCache.js';
+import { EntityFamilyMetadata, EntityMetadataView } from './EntityMetadata.js';
+import { BaseEntityValue, DataFromInit, DeepPartial, EntityChange, EntityEvents, ListEntity, ListItemInit, ListItemValue, ObjectEntity } from './types.js';
+import { EntityStoreEvents } from './EntityStore.js';
+export interface EntityInit {
+    oid: ObjectIdentifier;
+    schema: StorageFieldSchema;
+    entityFamily?: EntityCache;
+    metadataFamily: EntityFamilyMetadata;
+    parent?: Entity;
+    ctx: Context;
+    files: FileManager;
+    readonlyKeys?: string[];
+    fieldPath?: (string | number)[];
     patchCreator: PatchCreator;
-    addFile: (file: FileData) => void;
-    getFile: (id: string) => EntityFile;
-    time: TimestampProvider;
-    now: string;
-}
-export type AccessibleEntityProperty<T> = T extends Array<any> ? number : T extends object ? keyof T : never;
-type DataFromInit<Init> = Init extends {
-    [key: string]: any;
-} ? {
-    [Key in keyof Init]: Init[Key];
-} : Init extends Array<any> ? Init : any;
-export type EntityShape<E extends Entity<any, any>> = E extends Entity<infer Value, any> ? Value : never;
-type DeletableKeys<T> = keyof {
-    [Key in keyof T as IfNullableThen<T[Key], Key>]: Key;
-};
-type IfNullableThen<T, Out> = undefined extends T ? Out : null extends T ? Out : never;
-export declare function refreshEntity(entity: Entity<any, any>, info: EntityChangeInfo): void;
-export interface EntityChangeInfo {
-    isLocal?: boolean;
+    events: EntityStoreEvents;
 }
-type EntityEvents = {
-    change: (info: EntityChangeInfo) => void;
-    changeDeep: (target: Entity<any, any>, info: EntityChangeInfo) => void;
-    delete: (info: EntityChangeInfo) => void;
-    restore: (info: EntityChangeInfo) => void;
-};
-type BaseEntityValue = {
-    [Key: string]: any;
-} | any[];
-export declare class Entity<Init = any, KeyValue extends BaseEntityValue = any, Snapshot extends any = DataFromInit<Init>> implements ObjectEntity<Init, KeyValue, Snapshot>, ListEntity<Init, KeyValue, Snapshot> {
-    protected _current: any | null;
+export declare class Entity<Init = any, KeyValue extends BaseEntityValue = any, Snapshot extends any = DataFromInit<Init>> extends EventSubscriber<EntityEvents> implements ObjectEntity<Init, KeyValue, Snapshot>, ListEntity<Init, KeyValue, Snapshot> {
     readonly oid: ObjectIdentifier;
-    readonly fieldPath: string[];
-    readonly collection: string;
-    protected readonly store: StoreTools;
-    protected readonly fieldSchema: StorageFieldSchema | StorageFieldsSchema;
-    protected readonly cache: CacheTools;
-    protected _deleted: boolean;
-    protected parent: WeakRef<Entity<any, any>> | undefined;
-    protected readonly readonlyKeys: (keyof Init)[];
-    private cachedSnapshot;
-    private cachedDestructure;
+    private readonlyKeys;
+    private fieldPath;
+    private entityFamily;
+    private metadataFamily;
+    private schema;
+    private parent;
+    private ctx;
+    private files;
+    private patchCreator;
+    private events;
+    private _viewData;
+    private validationError;
     private cachedDeepUpdatedAt;
-    private _updatedAt;
-    protected events: EventSubscriber<EntityEvents>;
-    protected hasSubscribersToDeepChanges(): boolean;
-    get hasSubscribers(): boolean;
+    private wasDeletedLastChange;
+    private cachedView;
+    constructor({ oid, schema, entityFamily: childCache, parent, ctx, metadataFamily, readonlyKeys, files, patchCreator, events, }: EntityInit);
+    private onAdd;
+    private onReplace;
+    private onResetAll;
+    private get metadata();
+    /**
+     * The view of this Entity, not including nested
+     * entities (that's the snapshot - see #getSnapshot())
+     *
+     * Nested entities are represented by refs.
+     */
+    private get viewData();
+    /** convenience getter for viewData.view */
+    private get rawView();
+    /**
+     * An Entity's View includes the rendering of its underlying data,
+     * connecting of children where refs were, and validation
+     * and pruning according to schema.
+     */
+    private get view();
+    private childIsNull;
+    get uid(): string;
     get deleted(): boolean;
-    protected get value(): any;
+    get invalid(): boolean;
     get isList(): any;
-    get updatedAt(): number | null;
-    get deepUpdatedAt(): number | null;
-    get uid(): string;
-    constructor({ oid, store, fieldSchema, cache, parent, onAllUnsubscribed, readonlyKeys, fieldPath, }: {
-        oid: ObjectIdentifier;
-        store: StoreTools;
-        fieldSchema: StorageFieldSchema | StorageFieldsSchema;
-        cache: CacheTools;
-        parent?: Entity<any, any>;
-        onAllUnsubscribed?: () => void;
-        readonlyKeys?: (keyof Init)[];
-        fieldPath?: string[];
-    });
-    private [REFRESH];
-    private [DEEP_CHANGE];
-    protected getChildFieldSchema: (key: any) => any;
-    dispose: () => void;
-    subscribe: <EventName extends keyof EntityEvents>(event: EventName, callback: EntityEvents[EventName]) => () => void;
-    protected addPatches: (patches: Operation[]) => void;
-    protected cloneCurrent: () => any;
-    protected getSubObject: (oid: ObjectIdentifier, key: any) => Entity<any, any>;
-    protected wrapValue: <Key extends keyof KeyValue>(value: any, key: Key) => KeyValue[Key];
-    protected processInputValue: (value: any, key: any) => any;
-    get: <Key extends keyof KeyValue>(key: Key) => KeyValue[Key];
-    getAll: () => KeyValue;
-    private getFileSnapshot;
+    get updatedAt(): number;
+    get deepUpdatedAt(): number;
     /**
-     * Returns a copy of the entity and all sub-objects as
-     * a plain object or array.
+     * @internal - this is relevant to Verdant's system, not users.
+     *
+     * Indicates whether this document is from an outdated version
+     * of the schema - which means it cannot be used until it is upgraded.
      */
-    getSnapshot: () => any;
+    get isOutdatedVersion(): boolean;
     /**
-     * Object methods
+     * Pruning - when entities have invalid children, we 'prune' that
+     * data up to the nearest prunable point - a nullable field,
+     * or a list.
      */
-    keys: () => string[];
-    entries: () => [string, any][];
-    values: () => any[];
-    set: <Key extends keyof Init>(key: Key, value: Init[Key]) => void;
-    delete: (key: any) => void;
-    private getDeleteMode;
-    /** @deprecated - renamed to delete */
-    remove: (key: any) => void;
-    update: (value: DeepPartial<Init>, { replaceSubObjects, merge, }?: {
-        /**
-         * If true, merged sub-objects will be replaced entirely if there's
-         * ambiguity about their identity.
-         */
-        replaceSubObjects?: boolean | undefined;
-        /**
-         * If false, omitted keys will erase their respective fields.
-         */
-        merge?: boolean | undefined;
-    }) => void;
+    protected validate: (...args: unknown[]) => EntityValidationProblem | undefined;
+    private viewWithMappedChildren;
     /**
-     * List methods
+     * A current snapshot of this Entity's data, including nested
+     * Entities.
      */
+    getSnapshot: () => any;
+    private addPendingOperations;
+    private addConfirmedData;
+    private replaceAllData;
+    private resetAllData;
+    private change;
+    protected deepChange: (target: Entity, ev: EntityChange) => void;
+    private getChild;
+    /**
+     * Gets a value from this Entity. If the value
+     * is an object, it will be wrapped in another
+     * Entity.
+     */
+    get: <Key extends keyof KeyValue>(key: Key) => KeyValue[Key];
+    private processInputValue;
+    private getDeleteMode;
     /**
      * Returns the referent value of an item in the list, used for
      * operations which act on items. if the item is an object,
@@ -136,16 +103,29 @@ export declare class Entity<Init = any, KeyValue extends BaseEntityValue = any,
      * is a primitive, it will return the primitive.
      */
     private getItemRefValue;
-    get length(): any;
+    set: <Key extends keyof Init>(key: Key, value: Init[Key]) => void;
+    /**
+     * Returns a destructured version of this Entity, where child
+     * Entities are accessible at their respective keys.
+     */
+    getAll: () => KeyValue;
+    delete: (key: any) => void;
+    keys: () => string[];
+    entries: () => [string, Exclude<KeyValue[keyof KeyValue], undefined>][];
+    values: () => Exclude<KeyValue[keyof KeyValue], undefined>[];
+    update: (data: DeepPartial<Init>, { merge, replaceSubObjects, }?: {
+        replaceSubObjects?: boolean | undefined;
+        merge?: boolean | undefined;
+    }) => void;
+    get length(): number;
     push: (value: ListItemInit<Init>) => void;
     insert: (index: number, value: ListItemInit<Init>) => void;
     move: (from: number, to: number) => void;
     moveItem: (item: ListItemValue<KeyValue>, to: number) => void;
+    add: (value: ListItemValue<KeyValue>) => void;
     removeAll: (item: ListItemValue<KeyValue>) => void;
     removeFirst: (item: ListItemValue<KeyValue>) => void;
     removeLast: (item: ListItemValue<KeyValue>) => void;
-    add: (item: ListItemValue<KeyValue>) => void;
-    has: (item: ListItemValue<KeyValue>) => any;
     [Symbol.iterator](): {
         next: () => {
             readonly value: ListItemValue<KeyValue>;
@@ -155,66 +135,14 @@ export declare class Entity<Init = any, KeyValue extends BaseEntityValue = any,
             readonly done: true;
         };
     };
-    private getAsWrapped;
     map: <U>(callback: (value: ListItemValue<KeyValue>, index: number) => U) => U[];
     filter: (callback: (value: ListItemValue<KeyValue>, index: number) => boolean) => ListItemValue<KeyValue>[];
+    has: (value: ListItemValue<KeyValue>) => boolean;
     forEach: (callback: (value: ListItemValue<KeyValue>, index: number) => void) => void;
     some: (predicate: (value: ListItemValue<KeyValue>) => boolean) => boolean;
     every: (predicate: (value: ListItemValue<KeyValue>) => boolean) => boolean;
     find: (predicate: (value: ListItemValue<KeyValue>) => boolean) => ListItemValue<KeyValue> | undefined;
-    includes: (item: ListItemValue<KeyValue>) => any;
-}
-export interface BaseEntity<Init, Value extends BaseEntityValue, Snapshot = DataFromInit<Init>> {
-    dispose: () => void;
-    subscribe<EventName extends keyof EntityEvents>(event: EventName, callback: EntityEvents[EventName]): () => void;
-    get<Key extends keyof Value>(key: Key): Value[Key];
-    getAll(): Value;
-    getSnapshot(): Snapshot;
-    readonly deleted: boolean;
-    readonly hasSubscribers: boolean;
-}
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends Array<infer U> ? Array<DeepPartial<U>> : T[P] extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : DeepPartial<T[P]>;
-};
-export interface ObjectEntity<Init, Value extends BaseEntityValue, Snapshot = DataFromInit<Init>> extends BaseEntity<Init, Value, Snapshot> {
-    keys(): string[];
-    entries(): [string, Exclude<Value[keyof Value], undefined>][];
-    values(): Exclude<Value[keyof Value], undefined>[];
-    set<Key extends keyof Init>(key: Key, value: Init[Key]): void;
-    delete(key: DeletableKeys<Value>): void;
-    update(value: DeepPartial<Init>, options?: {
-        replaceSubObjects?: boolean;
-        merge?: boolean;
-    }): void;
-    readonly isList: false;
-}
-export interface ListEntity<Init, Value extends BaseEntityValue, Snapshot = DataFromInit<Init>> extends Iterable<ListItemValue<Value>>, BaseEntity<Init, Value, Snapshot> {
-    readonly isList: true;
-    readonly length: number;
-    push(value: ListItemInit<Init>): void;
-    insert(index: number, value: ListItemInit<Init>): void;
-    move(from: number, to: number): void;
-    moveItem(item: ListItemValue<Value>, to: number): void;
-    /**
-     * A Set operation which adds a value if an equivalent value is not already present.
-     * Object values are never the same.
-     */
-    add(value: ListItemValue<Value>): void;
-    removeAll(item: ListItemValue<Value>): void;
-    removeFirst(item: ListItemValue<Value>): void;
-    removeLast(item: ListItemValue<Value>): void;
-    map<U>(callback: (value: ListItemValue<Value>, index: number) => U): U[];
-    filter(callback: (value: ListItemValue<Value>, index: number) => boolean): ListItemValue<Value>[];
-    delete(index: number): void;
-    has(value: ListItemValue<Value>): boolean;
-    forEach(callback: (value: ListItemValue<Value>, index: number) => void): void;
-    some(predicate: (value: ListItemValue<Value>) => boolean): boolean;
-    every(predicate: (value: ListItemValue<Value>) => boolean): boolean;
-    find(predicate: (value: ListItemValue<Value>) => boolean): ListItemValue<Value> | undefined;
-    includes(value: ListItemValue<Value>): boolean;
+    includes: (value: ListItemValue<KeyValue>) => boolean;
+    __getViewData__: (oid: ObjectIdentifier, type: 'confirmed' | 'pending') => EntityMetadataView;
+    __getFamilyOids__: () => string[];
 }
-export type AnyEntity<Init, KeyValue extends BaseEntityValue, Snapshot extends any> = ListEntity<Init, KeyValue, Snapshot> | ObjectEntity<Init, KeyValue, Snapshot>;
-type ListItemValue<KeyValue> = KeyValue extends Array<infer T> ? T : never;
-type ListItemInit<Init> = Init extends Array<infer T> ? T : never;
-export type EntityDestructured<T extends AnyEntity<any, any, any> | null> = (T extends ListEntity<any, infer KeyValue, any> ? KeyValue : T extends ObjectEntity<any, infer KeyValue, any> ? KeyValue : never) | (T extends null ? null : never);
-export {};