jazz-tools 0.17.3 → 0.17.5

package/src/tools/coValues/coList.ts

@@ -1,5 +1,5 @@
-import type { JsonValue, RawCoList } from "cojson";
-import { ControlledAccount, RawAccount } from "cojson";
+import type { JsonValue, RawCoList, CoValueUniqueness, RawCoID } from "cojson";
+import { ControlledAccount, RawAccount, cojsonInternals } from "cojson";
 import { calcPatch } from "fast-myers-diff";
 import type {
   Account,
@@ -24,6 +24,7 @@ import {
   RegisteredSchemas,
   SchemaInit,
   accessChildByKey,
+  activeAccountContext,
   coField,
   coValueClassFromCoValueClassOrSchema,
   coValuesCache,
@@ -236,12 +237,21 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
   static create<L extends CoList>(
     this: CoValueClass<L>,
     items: L[number][],
-    options?: { owner: Account | Group } | Account | Group,
+    options?:
+      | {
+          owner: Account | Group;
+          unique?: CoValueUniqueness["uniqueness"];
+        }
+      | Account
+      | Group,
   ) {
-    const { owner } = parseCoValueCreateOptions(options);
+    const { owner, uniqueness } = parseCoValueCreateOptions(options);
     const instance = new this({ init: items, owner });
     const raw = owner._raw.createList(
       toRawItems(items, instance._schema[ItemsSym], owner),
+      null,
+      "private",
+      uniqueness,
     );
 
     Object.defineProperties(instance, {
@@ -546,6 +556,116 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
     return cl.fromRaw(this._raw) as InstanceType<Cl>;
   }
 
+  /** @deprecated Use `CoList.upsertUnique` and `CoList.loadUnique` instead. */
+  static findUnique<L extends CoList>(
+    this: CoValueClass<L>,
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    as?: Account | Group | AnonymousJazzAgent,
+  ) {
+    return CoList._findUnique(unique, ownerID, as);
+  }
+
+  /** @internal */
+  static _findUnique<L extends CoList>(
+    this: CoValueClass<L>,
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    as?: Account | Group | AnonymousJazzAgent,
+  ) {
+    as ||= activeAccountContext.get();
+
+    const header = {
+      type: "colist" as const,
+      ruleset: {
+        type: "ownedByGroup" as const,
+        group: ownerID as RawCoID,
+      },
+      meta: null,
+      uniqueness: unique,
+    };
+    const crypto =
+      as._type === "Anonymous" ? as.node.crypto : as._raw.core.node.crypto;
+    return cojsonInternals.idforHeader(header, crypto) as ID<L>;
+  }
+
+  /**
+   * Given some data, updates an existing CoList or initialises a new one if none exists.
+   *
+   * Note: This method respects resolve options, and thus can return `null` if the references cannot be resolved.
+   *
+   * @example
+   * ```ts
+   * const activeItems = await ItemList.upsertUnique(
+   *   {
+   *     value: [item1, item2, item3],
+   *     unique: sourceData.identifier,
+   *     owner: workspace,
+   *   }
+   * );
+   * ```
+   *
+   * @param options The options for creating or loading the CoList. This includes the intended state of the CoList, its unique identifier, its owner, and the references to resolve.
+   * @returns Either an existing & modified CoList, or a new initialised CoList if none exists.
+   * @category Subscription & Loading
+   */
+  static async upsertUnique<
+    L extends CoList,
+    const R extends RefsToResolve<L> = true,
+  >(
+    this: CoValueClass<L>,
+    options: {
+      value: L[number][];
+      unique: CoValueUniqueness["uniqueness"];
+      owner: Account | Group;
+      resolve?: RefsToResolveStrict<L, R>;
+    },
+  ): Promise<Resolved<L, R> | null> {
+    let listId = CoList._findUnique(options.unique, options.owner.id);
+    let list: Resolved<L, R> | null = await loadCoValueWithoutMe(this, listId, {
+      ...options,
+      loadAs: options.owner._loadedAs,
+      skipRetry: true,
+    });
+    if (!list) {
+      list = (this as any).create(options.value, {
+        owner: options.owner,
+        unique: options.unique,
+      }) as Resolved<L, R>;
+    } else {
+      (list as L).applyDiff(options.value);
+    }
+
+    return await loadCoValueWithoutMe(this, listId, {
+      ...options,
+      loadAs: options.owner._loadedAs,
+      skipRetry: true,
+    });
+  }
+
+  /**
+   * Loads a CoList by its unique identifier and owner's ID.
+   * @param unique The unique identifier of the CoList to load.
+   * @param ownerID The ID of the owner of the CoList.
+   * @param options Additional options for loading the CoList.
+   * @returns The loaded CoList, or null if unavailable.
+   */
+  static loadUnique<L extends CoList, const R extends RefsToResolve<L> = true>(
+    this: CoValueClass<L>,
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    options?: {
+      resolve?: RefsToResolveStrict<L, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<L, R> | null> {
+    return loadCoValueWithoutMe(
+      this,
+      CoList._findUnique(unique, ownerID, options?.loadAs),
+      { ...options, skipRetry: true },
+    );
+  }
+
   /**
    * Wait for the `CoList` to be uploaded to the other peers.
    *

package/src/tools/exports.ts

@@ -54,6 +54,7 @@ export {
   SubscriptionScope,
   exportCoValue,
   importContentPieces,
+  Ref,
 } from "./internal.js";
 
 export {

package/src/tools/implementation/zodSchema/schemaTypes/CoListSchema.ts

@@ -2,12 +2,14 @@ import {
   Account,
   CoList,
   Group,
+  ID,
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
   SubscribeListenerOptions,
   coOptionalDefiner,
 } from "../../../internal.js";
+import { CoValueUniqueness } from "cojson";
 import { AnonymousJazzAgent } from "../../anonymousJazzAgent.js";
 import { CoListInit } from "../typeConverters/CoFieldInit.js";
 import { InstanceOrPrimitiveOfSchema } from "../typeConverters/InstanceOrPrimitiveOfSchema.js";
@@ -29,7 +31,13 @@ export class CoListSchema<T extends AnyZodOrCoValueSchema>
 
   create(
     items: CoListInit<T>,
-    options?: { owner: Account | Group } | Account | Group,
+    options?:
+      | {
+          owner: Account | Group;
+          unique?: CoValueUniqueness["uniqueness"];
+        }
+      | Account
+      | Group,
   ): CoListInstance<T> {
     return this.coValueClass.create(items as any, options) as CoListInstance<T>;
   }
@@ -62,6 +70,41 @@ export class CoListSchema<T extends AnyZodOrCoValueSchema>
     return this.coValueClass;
   }
 
+  /** @deprecated Use `CoList.upsertUnique` and `CoList.loadUnique` instead. */
+  findUnique(
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    as?: Account | Group | AnonymousJazzAgent,
+  ): ID<CoListInstanceCoValuesNullable<T>> {
+    return this.coValueClass.findUnique(unique, ownerID, as);
+  }
+
+  upsertUnique<
+    const R extends RefsToResolve<CoListInstanceCoValuesNullable<T>> = true,
+  >(options: {
+    value: CoListInit<T>;
+    unique: CoValueUniqueness["uniqueness"];
+    owner: Account | Group;
+    resolve?: RefsToResolveStrict<CoListInstanceCoValuesNullable<T>, R>;
+  }): Promise<Resolved<CoListInstanceCoValuesNullable<T>, R> | null> {
+    // @ts-expect-error
+    return this.coValueClass.upsertUnique(options);
+  }
+
+  loadUnique<
+    const R extends RefsToResolve<CoListInstanceCoValuesNullable<T>> = true,
+  >(
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    options?: {
+      resolve?: RefsToResolveStrict<CoListInstanceCoValuesNullable<T>, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<CoListInstanceCoValuesNullable<T>, R> | null> {
+    // @ts-expect-error
+    return this.coValueClass.loadUnique(unique, ownerID, options);
+  }
+
   optional(): CoOptionalSchema<this> {
     return coOptionalDefiner(this);
   }

package/src/tools/implementation/zodSchema/schemaTypes/CoRecordSchema.ts

@@ -72,12 +72,37 @@ export interface CoRecordSchema<
     ) => void,
   ): () => void;
 
+  /** @deprecated Use `CoMap.upsertUnique` and `CoMap.loadUnique` instead. */
   findUnique(
     unique: CoValueUniqueness["uniqueness"],
     ownerID: ID<Account> | ID<Group>,
     as?: Account | Group | AnonymousJazzAgent,
   ): ID<CoRecordInstanceCoValuesNullable<K, V>>;
 
+  upsertUnique<
+    const R extends RefsToResolve<
+      CoRecordInstanceCoValuesNullable<K, V>
+    > = true,
+  >(options: {
+    value: Simplify<CoRecordInit<K, V>>;
+    unique: CoValueUniqueness["uniqueness"];
+    owner: Account | Group;
+    resolve?: RefsToResolveStrict<CoRecordInstanceCoValuesNullable<K, V>, R>;
+  }): Promise<Resolved<CoRecordInstanceCoValuesNullable<K, V>, R> | null>;
+
+  loadUnique<
+    const R extends RefsToResolve<
+      CoRecordInstanceCoValuesNullable<K, V>
+    > = true,
+  >(
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    options?: {
+      resolve?: RefsToResolveStrict<CoRecordInstanceCoValuesNullable<K, V>, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<CoRecordInstanceCoValuesNullable<K, V>, R> | null>;
+
   getCoValueClass: () => typeof CoMap;
 
   optional(): CoOptionalSchema<this>;

package/src/tools/tests/coList.test.ts

@@ -863,6 +863,173 @@ describe("CoList subscription", async () => {
   });
 });
 
+describe("CoList unique methods", () => {
+  test("loadUnique returns existing list", async () => {
+    const ItemList = co.list(z.string());
+    const group = Group.create();
+
+    const originalList = ItemList.create(["item1", "item2", "item3"], {
+      owner: group,
+      unique: "test-list",
+    });
+
+    const foundList = await ItemList.loadUnique("test-list", group.id);
+    expect(foundList).toEqual(originalList);
+    expect(foundList?.length).toBe(3);
+    expect(foundList?.[0]).toBe("item1");
+  });
+
+  test("loadUnique returns null for non-existent list", async () => {
+    const ItemList = co.list(z.string());
+    const group = Group.create();
+
+    const foundList = await ItemList.loadUnique("non-existent", group.id);
+    expect(foundList).toBeNull();
+  });
+
+  test("upsertUnique creates new list when none exists", async () => {
+    const ItemList = co.list(z.string());
+    const group = Group.create();
+
+    const sourceData = ["item1", "item2", "item3"];
+
+    const result = await ItemList.upsertUnique({
+      value: sourceData,
+      unique: "new-list",
+      owner: group,
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.length).toBe(3);
+    expect(result?.[0]).toBe("item1");
+    expect(result?.[1]).toBe("item2");
+    expect(result?.[2]).toBe("item3");
+  });
+
+  test("upsertUnique updates existing list", async () => {
+    const ItemList = co.list(z.string());
+    const group = Group.create();
+
+    // Create initial list
+    const originalList = ItemList.create(["original1", "original2"], {
+      owner: group,
+      unique: "update-list",
+    });
+
+    // Upsert with new data
+    const updatedList = await ItemList.upsertUnique({
+      value: ["updated1", "updated2", "updated3"],
+      unique: "update-list",
+      owner: group,
+    });
+
+    expect(updatedList).toEqual(originalList); // Should be the same instance
+    expect(updatedList?.length).toBe(3);
+    expect(updatedList?.[0]).toBe("updated1");
+    expect(updatedList?.[1]).toBe("updated2");
+    expect(updatedList?.[2]).toBe("updated3");
+  });
+
+  test("upsertUnique with CoValue items", async () => {
+    const Item = co.map({
+      name: z.string(),
+      value: z.number(),
+    });
+    const ItemList = co.list(Item);
+    const group = Group.create();
+
+    const items = [
+      Item.create({ name: "First", value: 1 }, group),
+      Item.create({ name: "Second", value: 2 }, group),
+    ];
+
+    const result = await ItemList.upsertUnique({
+      value: items,
+      unique: "item-list",
+      owner: group,
+      resolve: { $each: true },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.length).toBe(2);
+    expect(result?.[0]?.name).toBe("First");
+    expect(result?.[1]?.name).toBe("Second");
+  });
+
+  test("upsertUnique updates list with CoValue items", async () => {
+    const Item = co.map({
+      name: z.string(),
+      value: z.number(),
+    });
+    const ItemList = co.list(Item);
+    const group = Group.create();
+
+    // Create initial list
+    const initialItems = [Item.create({ name: "Initial", value: 0 }, group)];
+    const originalList = ItemList.create(initialItems, {
+      owner: group,
+      unique: "updateable-item-list",
+    });
+
+    // Upsert with new items
+    const newItems = [
+      Item.create({ name: "Updated", value: 1 }, group),
+      Item.create({ name: "Added", value: 2 }, group),
+    ];
+
+    const updatedList = await ItemList.upsertUnique({
+      value: newItems,
+      unique: "updateable-item-list",
+      owner: group,
+      resolve: { $each: true },
+    });
+
+    expect(updatedList).toEqual(originalList); // Should be the same instance
+    expect(updatedList?.length).toBe(2);
+    expect(updatedList?.[0]?.name).toBe("Updated");
+    expect(updatedList?.[1]?.name).toBe("Added");
+  });
+
+  test("findUnique returns correct ID", async () => {
+    const ItemList = co.list(z.string());
+    const group = Group.create();
+
+    const originalList = ItemList.create(["test"], {
+      owner: group,
+      unique: "find-test",
+    });
+
+    const foundId = ItemList.findUnique("find-test", group.id);
+    expect(foundId).toBe(originalList.id);
+  });
+
+  test("upsertUnique with resolve options", async () => {
+    const Category = co.map({ title: z.string() });
+    const Item = co.map({
+      name: z.string(),
+      category: Category,
+    });
+    const ItemList = co.list(Item);
+    const group = Group.create();
+
+    const category = Category.create({ title: "Category 1" }, group);
+
+    const items = [Item.create({ name: "Item 1", category }, group)];
+
+    const result = await ItemList.upsertUnique({
+      value: items,
+      unique: "resolved-list",
+      owner: group,
+      resolve: { $each: { category: true } },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.length).toBe(1);
+    expect(result?.[0]?.name).toBe("Item 1");
+    expect(result?.[0]?.category?.title).toBe("Category 1");
+  });
+});
+
 describe("co.list schema", () => {
   test("can access the inner schema of a co.list", () => {
     const Keywords = co.list(co.plainText());

package/src/tools/tests/coMap.record.test.ts

@@ -460,3 +460,107 @@ describe("CoMap.Record", async () => {
     }
   });
 });
+
+describe("CoRecord unique methods", () => {
+  test("loadUnique returns existing record", async () => {
+    const ItemRecord = co.record(z.string(), z.number());
+    const group = Group.create();
+
+    const originalRecord = ItemRecord.create(
+      { item1: 1, item2: 2, item3: 3 },
+      { owner: group, unique: "test-record" },
+    );
+
+    const foundRecord = await ItemRecord.loadUnique("test-record", group.id);
+    expect(foundRecord).toEqual(originalRecord);
+    expect(foundRecord?.item1).toBe(1);
+    expect(foundRecord?.item2).toBe(2);
+  });
+
+  test("loadUnique returns null for non-existent record", async () => {
+    const ItemRecord = co.record(z.string(), z.number());
+    const group = Group.create();
+
+    const foundRecord = await ItemRecord.loadUnique("non-existent", group.id);
+    expect(foundRecord).toBeNull();
+  });
+
+  test("upsertUnique creates new record when none exists", async () => {
+    const ItemRecord = co.record(z.string(), z.number());
+    const group = Group.create();
+
+    const sourceData = { item1: 1, item2: 2, item3: 3 };
+
+    const result = await ItemRecord.upsertUnique({
+      value: sourceData,
+      unique: "new-record",
+      owner: group,
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.item1).toBe(1);
+    expect(result?.item2).toBe(2);
+    expect(result?.item3).toBe(3);
+  });
+
+  test("upsertUnique updates existing record", async () => {
+    const ItemRecord = co.record(z.string(), z.number());
+    const group = Group.create();
+
+    // Create initial record
+    const originalRecord = ItemRecord.create(
+      { original1: 1, original2: 2 },
+      { owner: group, unique: "update-record" },
+    );
+
+    // Upsert with new data
+    const updatedRecord = await ItemRecord.upsertUnique({
+      value: { updated1: 10, updated2: 20, updated3: 30 },
+      unique: "update-record",
+      owner: group,
+    });
+
+    expect(updatedRecord).toEqual(originalRecord); // Should be the same instance
+    expect(updatedRecord?.updated1).toBe(10);
+    expect(updatedRecord?.updated2).toBe(20);
+    expect(updatedRecord?.updated3).toBe(30);
+  });
+
+  test("upsertUnique with CoValue items", async () => {
+    const Item = co.map({
+      name: z.string(),
+      value: z.number(),
+    });
+    const ItemRecord = co.record(z.string(), Item);
+    const group = Group.create();
+
+    const items = {
+      first: Item.create({ name: "First", value: 1 }, group),
+      second: Item.create({ name: "Second", value: 2 }, group),
+    };
+
+    const result = await ItemRecord.upsertUnique({
+      value: items,
+      unique: "item-record",
+      owner: group,
+      resolve: { first: true, second: true },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.first?.name).toBe("First");
+    expect(result?.second?.name).toBe("Second");
+  });
+
+  test("findUnique returns correct ID", async () => {
+    const ItemRecord = co.record(z.string(), z.string());
+    const group = Group.create();
+
+    const originalRecord = ItemRecord.create(
+      { test: "value" },
+      { owner: group, unique: "find-test" },
+    );
+
+    const foundId = ItemRecord.findUnique("find-test", group.id);
+    expect(foundId).toBe(originalRecord.id);
+  });
+});