jazz-tools 0.10.14 → 0.11.0

package/dist/coValues/coList.d.ts

@@ -0,0 +1,221 @@
+import type { RawCoList } from "cojson";
+import type { CoValue, CoValueClass, CoValueFromRaw, DeeplyLoaded, DepthsIn, ID, SchemaFor, UnCo } from "../internal.js";
+import { AnonymousJazzAgent, ItemsSym, Ref, inspect } from "../internal.js";
+import { type Account } from "./account.js";
+import { type Group } from "./group.js";
+/**
+ * CoLists are collaborative versions of plain arrays.
+ *
+ * @categoryDescription Content
+ * You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.
+ *
+ * Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.
+ *
+ * ```ts
+ * colorList[0];
+ * colorList[3] = "yellow";
+ * colorList.push("Kawazaki Green");
+ * colorList.splice(1, 1);
+ * ```
+ *
+ * @category CoValues
+ */
+export declare class CoList<Item = any> extends Array<Item> implements CoValue {
+    /**
+     * Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
+     *
+     * @example
+     * ```ts
+     * class ColorList extends CoList.Of(
+     *   co.string
+     * ) {}
+     * class AnimalList extends CoList.Of(
+     *   co.ref(Animal)
+     * ) {}
+     * ```
+     *
+     * @category Declaration
+     */
+    static Of<Item>(item: Item): typeof CoList<Item>;
+    /**
+     * @ignore
+     * @deprecated Use UPPERCASE `CoList.Of` instead! */
+    static of(..._args: never): never;
+    /**
+     * The ID of this `CoList`
+     * @category Content */
+    id: ID<this>;
+    /** @category Type Helpers */
+    _type: "CoList";
+    /** @category Internals */
+    _raw: RawCoList;
+    /** @category Internals */
+    _instanceID: string;
+    /** @internal This is only a marker type and doesn't exist at runtime */
+    [ItemsSym]: Item;
+    /** @internal */
+    static _schema: any;
+    /** @internal */
+    get _schema(): {
+        [ItemsSym]: SchemaFor<Item>;
+    };
+    /** @category Collaboration */
+    get _owner(): Account | Group;
+    /**
+     * If a `CoList`'s items are a `co.ref(...)`, you can use `coList._refs[i]` to access
+     * the `Ref` instead of the potentially loaded/null value.
+     *
+     * This allows you to always get the ID or load the value manually.
+     *
+     * @example
+     * ```ts
+     * animals._refs[0].id; // => ID<Animal>
+     * animals._refs[0].value;
+     * // => Animal | null
+     * const animal = await animals._refs[0].load();
+     * ```
+     *
+     * @category Content
+     **/
+    get _refs(): {
+        [idx: number]: Exclude<Item, null> extends CoValue ? Ref<UnCo<Exclude<Item, null>>> : never;
+    } & {
+        length: number;
+        [Symbol.iterator](): IterableIterator<Exclude<Item, null> extends CoValue ? Ref<Exclude<Item, null>> : never>;
+    };
+    get _edits(): {
+        [idx: number]: {
+            value?: Item;
+            ref?: Item extends CoValue ? Ref<Item> : never;
+            by?: Account;
+            madeAt: Date;
+        };
+    };
+    get _loadedAs(): Account | AnonymousJazzAgent;
+    static get [Symbol.species](): ArrayConstructor;
+    constructor(options: {
+        fromRaw: RawCoList;
+    } | undefined);
+    /**
+     * Create a new CoList with the given initial values and owner.
+     *
+     * The owner (a Group or Account) determines access rights to the CoMap.
+     *
+     * The CoList will immediately be persisted and synced to connected peers.
+     *
+     * @example
+     * ```ts
+     * const colours = ColorList.create(
+     *   ["red", "green", "blue"],
+     *   { owner: me }
+     * );
+     * const animals = AnimalList.create(
+     *   [cat, dog, fish],
+     *   { owner: me }
+     * );
+     * ```
+     *
+     * @category Creation
+     **/
+    static create<L extends CoList>(this: CoValueClass<L>, items: UnCo<L[number]>[], options?: {
+        owner: Account | Group;
+    } | Account | Group): L;
+    push(...items: Item[]): number;
+    unshift(...items: Item[]): number;
+    pop(): Item | undefined;
+    shift(): Item | undefined;
+    splice(start: number, deleteCount: number, ...items: Item[]): Item[];
+    toJSON(_key?: string, seenAbove?: ID<CoValue>[]): any[];
+    [inspect](): any[];
+    /** @category Internals */
+    static fromRaw<V extends CoList>(this: CoValueClass<V> & typeof CoList, raw: RawCoList): V & CoList<any>;
+    /** @internal */
+    static schema<V extends CoList>(this: {
+        new (...args: any): V;
+    } & typeof CoList, def: {
+        [ItemsSym]: V["_schema"][ItemsSym];
+    }): void;
+    /**
+     * Load a `CoList` with a given ID, as a given account.
+     *
+     * `depth` specifies if item CoValue references should be loaded as well before resolving.
+     * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+     *
+     * You can pass `[]` or for shallowly loading only this CoList, or `[itemDepth]` for recursively loading referenced CoValues.
+     *
+     * Check out the `load` methods on `CoMap`/`CoList`/`CoFeed`/`Group`/`Account` to see which depth structures are valid to nest.
+     *
+     * @example
+     * ```ts
+     * const animalsWithVets =
+     *   await ListOfAnimals.load(
+     *     "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+     *     me,
+     *     [{ vet: {} }]
+     *   );
+     * ```
+     *
+     * @category Subscription & Loading
+     */
+    static load<C extends CoList, Depth>(this: CoValueClass<C>, id: ID<C>, depth: Depth & DepthsIn<C>): Promise<DeeplyLoaded<C, Depth> | undefined>;
+    static load<C extends CoList, Depth>(this: CoValueClass<C>, id: ID<C>, as: Account, depth: Depth & DepthsIn<C>): Promise<DeeplyLoaded<C, Depth> | undefined>;
+    /**
+     * Load and subscribe to a `CoList` with a given ID, as a given account.
+     *
+     * Automatically also subscribes to updates to all referenced/nested CoValues as soon as they are accessed in the listener.
+     *
+     * `depth` specifies if item CoValue references should be loaded as well before calling `listener` for the first time.
+     * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+     *
+     * You can pass `[]` or for shallowly loading only this CoList, or `[itemDepth]` for recursively loading referenced CoValues.
+     *
+     * Check out the `load` methods on `CoMap`/`CoList`/`CoFeed`/`Group`/`Account` to see which depth structures are valid to nest.
+     *
+     * Returns an unsubscribe function that you should call when you no longer need updates.
+     *
+     * Also see the `useCoState` hook to reactively subscribe to a CoValue in a React component.
+     *
+     * @example
+     * ```ts
+     * const unsub = ListOfAnimals.subscribe(
+     *   "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+     *   me,
+     *   { vet: {} },
+     *   (animalsWithVets) => console.log(animalsWithVets)
+     * );
+     * ```
+     *
+     * @category Subscription & Loading
+     */
+    static subscribe<C extends CoList, Depth>(this: CoValueClass<C>, id: ID<C>, depth: Depth & DepthsIn<C>, listener: (value: DeeplyLoaded<C, Depth>) => void): () => void;
+    static subscribe<C extends CoList, Depth>(this: CoValueClass<C>, id: ID<C>, as: Account, depth: Depth & DepthsIn<C>, listener: (value: DeeplyLoaded<C, Depth>) => void): () => void;
+    /**
+     * Given an already loaded `CoList`, ensure that items are loaded to the specified depth.
+     *
+     * Works like `CoList.load()`, but you don't need to pass the ID or the account to load as again.
+     *
+     * @category Subscription & Loading
+     */
+    ensureLoaded<L extends CoList, Depth>(this: L, depth: Depth & DepthsIn<L>): Promise<DeeplyLoaded<L, Depth>>;
+    /**
+     * Given an already loaded `CoList`, subscribe to updates to the `CoList` and ensure that items are loaded to the specified depth.
+     *
+     * Works like `CoList.subscribe()`, but you don't need to pass the ID or the account to load as again.
+     *
+     * Returns an unsubscribe function that you should call when you no longer need updates.
+     *
+     * @category Subscription & Loading
+     **/
+    subscribe<L extends CoList, Depth>(this: L, depth: Depth & DepthsIn<L>, listener: (value: DeeplyLoaded<L, Depth>) => void): () => void;
+    /** @category Type Helpers */
+    castAs<Cl extends CoValueClass & CoValueFromRaw<CoValue>>(cl: Cl): InstanceType<Cl>;
+    /**
+     * Wait for the `CoList` to be uploaded to the other peers.
+     *
+     * @category Subscription & Loading
+     */
+    waitForSync(options?: {
+        timeout?: number;
+    }): Promise<unknown[]>;
+}
+//# sourceMappingURL=coList.d.ts.map

package/dist/coValues/coList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coList.d.ts","sourceRoot":"","sources":["../../src/coValues/coList.ts"],"names":[],"mappings":"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"}