jazz-tools 0.15.0 → 0.15.1

package/src/tools/coValues/coMap.ts

@@ -10,12 +10,10 @@ import {
 } from "cojson";
 import type {
   AnonymousJazzAgent,
-  AnyAccountSchema,
   CoValue,
   CoValueClass,
   Group,
   ID,
-  InstanceOfSchema,
   RefEncoded,
   RefIfCoValue,
   RefsToResolve,
@@ -319,18 +317,7 @@ export class CoMap extends CoValueBase implements CoValue {
   ) {
     const instance = new this();
 
-    const { owner, uniqueness } = parseCoValueCreateOptions(options);
-    const raw = instance.rawFromInit(init, owner, uniqueness);
-
-    Object.defineProperties(instance, {
-      id: {
-        value: raw.id,
-        enumerable: false,
-      },
-      _raw: { value: raw, enumerable: false },
-    });
-
-    return instance;
+    return instance._createCoMap(init, options);
   }
 
   /**
@@ -388,6 +375,30 @@ export class CoMap extends CoValueBase implements CoValue {
     return this.toJSON();
   }
 
+  _createCoMap(
+    init: Simplify<CoMapInit<typeof this>>,
+    options?:
+      | {
+          owner: Account | Group;
+          unique?: CoValueUniqueness["uniqueness"];
+        }
+      | Account
+      | Group,
+  ): typeof this {
+    const { owner, uniqueness } = parseCoValueCreateOptions(options);
+    const raw = this.rawFromInit(init, owner, uniqueness);
+
+    Object.defineProperties(this, {
+      id: {
+        value: raw.id,
+        enumerable: false,
+      },
+      _raw: { value: raw, enumerable: false },
+    });
+
+    return this;
+  }
+
   /**
    * Create a new `RawCoMap` from an initialization object
    * @internal
@@ -490,6 +501,7 @@ export class CoMap extends CoValueBase implements CoValue {
     options?: {
       resolve?: RefsToResolveStrict<M, R>;
       loadAs?: Account | AnonymousJazzAgent;
+      skipRetry?: boolean;
     },
   ): Promise<Resolved<M, R> | null> {
     return loadCoValueWithoutMe(this, id, options);
@@ -542,11 +554,22 @@ export class CoMap extends CoValueBase implements CoValue {
     return subscribeToCoValueWithoutMe<M, R>(this, id, options, listener);
   }
 
+  /** @deprecated Use `CoMap.upsertUnique` and `CoMap.loadUnique` instead. */
   static findUnique<M extends CoMap>(
     this: CoValueClass<M>,
     unique: CoValueUniqueness["uniqueness"],
     ownerID: ID<Account> | ID<Group>,
     as?: Account | Group | AnonymousJazzAgent,
+  ) {
+    return CoMap._findUnique(unique, ownerID, as);
+  }
+
+  /** @internal */
+  static _findUnique<M extends CoMap>(
+    this: CoValueClass<M>,
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    as?: Account | Group | AnonymousJazzAgent,
   ) {
     as ||= activeAccountContext.get();
 
@@ -564,6 +587,87 @@ export class CoMap extends CoValueBase implements CoValue {
     return cojsonInternals.idforHeader(header, crypto) as ID<M>;
   }
 
+  /**
+   * Given some data, updates an existing CoMap 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 activeEvent = await Event.upsertUnique(
+   *   sourceData.identifier,
+   *   workspace.id,
+   *   {
+   *     title: sourceData.title,
+   *     identifier: sourceData.identifier,
+   *     external_id: sourceData._id,
+   *   },
+   *   workspace
+   * );
+   * ```
+   *
+   * @param options The options for creating or loading the CoMap. This includes the intended state of the CoMap, its unique identifier, its owner, and the references to resolve.
+   * @returns Either an existing & modified CoMap, or a new initialised CoMap if none exists.
+   * @category Subscription & Loading
+   */
+  static async upsertUnique<
+    M extends CoMap,
+    const R extends RefsToResolve<M> = true,
+  >(
+    this: CoValueClass<M>,
+    options: {
+      value: Simplify<CoMapInit<M>>;
+      unique: CoValueUniqueness["uniqueness"];
+      owner: Account | Group;
+      resolve?: RefsToResolveStrict<M, R>;
+    },
+  ): Promise<Resolved<M, R> | null> {
+    let mapId = CoMap._findUnique(options.unique, options.owner.id);
+    let map: Resolved<M, R> | null = await loadCoValueWithoutMe(this, mapId, {
+      ...options,
+      loadAs: options.owner._loadedAs,
+      skipRetry: true,
+    });
+    if (!map) {
+      const instance = new this();
+      map = instance._createCoMap(options.value, {
+        owner: options.owner,
+        unique: options.unique,
+      }) as Resolved<M, R>;
+    } else {
+      (map as M).applyDiff(options.value as Partial<CoMapInit<M>>);
+    }
+
+    return await loadCoValueWithoutMe(this, mapId, {
+      ...options,
+      loadAs: options.owner._loadedAs,
+      skipRetry: true,
+    });
+  }
+
+  /**
+   * Loads a CoMap by its unique identifier and owner's ID.
+   * @param unique The unique identifier of the CoMap to load.
+   * @param ownerID The ID of the owner of the CoMap.
+   * @param options Additional options for loading the CoMap.
+   * @returns The loaded CoMap, or null if unavailable.
+   */
+  static loadUnique<M extends CoMap, const R extends RefsToResolve<M> = true>(
+    this: CoValueClass<M>,
+    unique: CoValueUniqueness["uniqueness"],
+    ownerID: ID<Account> | ID<Group>,
+    options?: {
+      resolve?: RefsToResolveStrict<M, R>;
+      loadAs?: Account | AnonymousJazzAgent;
+    },
+  ): Promise<Resolved<M, R> | null> {
+    return loadCoValueWithoutMe(
+      this,
+      CoMap._findUnique(unique, ownerID, options?.loadAs),
+      { ...options, skipRetry: true },
+    );
+  }
+
   /**
    * Given an already loaded `CoMap`, ensure that the specified fields are loaded to the specified depth.
    *

package/src/tools/coValues/interfaces.ts

@@ -90,6 +90,7 @@ export function loadCoValueWithoutMe<
   options?: {
     resolve?: RefsToResolveStrict<V, R>;
     loadAs?: Account | AnonymousJazzAgent;
+    skipRetry?: boolean;
   },
 ): Promise<Resolved<V, R> | null> {
   return loadCoValue(cls, id, {
@@ -107,6 +108,7 @@ export function loadCoValue<
   options: {
     resolve?: RefsToResolveStrict<V, R>;
     loadAs: Account | AnonymousJazzAgent;
+    skipRetry?: boolean;
   },
 ): Promise<Resolved<V, R> | null> {
   return new Promise((resolve) => {
@@ -117,6 +119,7 @@ export function loadCoValue<
         resolve: options.resolve,
         loadAs: options.loadAs,
         syncResolution: true,
+        skipRetry: options.skipRetry,
         onUnavailable: () => {
           resolve(null);
         },
@@ -242,6 +245,7 @@ export function subscribeToCoValue<
     onUnavailable?: () => void;
     onUnauthorized?: () => void;
     syncResolution?: boolean;
+    skipRetry?: boolean;
   },
   listener: SubscribeListener<V, R>,
 ): () => void {
@@ -252,10 +256,16 @@ export function subscribeToCoValue<
 
   let unsubscribed = false;
 
-  const rootNode = new SubscriptionScope<V>(node, resolve, id as ID<V>, {
-    ref: cls,
-    optional: false,
-  });
+  const rootNode = new SubscriptionScope<V>(
+    node,
+    resolve,
+    id as ID<V>,
+    {
+      ref: cls,
+      optional: false,
+    },
+    options.skipRetry,
+  );
 
   const handleUpdate = (value: SubscriptionValue<V, any>) => {
     if (unsubscribed) return;

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

@@ -57,6 +57,7 @@ export type CoMapSchema<
           R
         >;
         loadAs?: Account | AnonymousJazzAgent;
+        skipRetry?: boolean;
       },
     ): Promise<Resolved<
       Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap,
@@ -82,12 +83,49 @@ export type CoMapSchema<
       ) => void,
     ): () => void;
 
+    /** @deprecated Use `CoMap.upsertUnique` and `CoMap.loadUnique` instead. */
     findUnique(
       unique: CoValueUniqueness["uniqueness"],
       ownerID: string,
       as?: Account | Group | AnonymousJazzAgent,
     ): string;
 
+    upsertUnique: <
+      const R extends RefsToResolve<
+        Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap
+      > = true,
+    >(options: {
+      value: Simplify<CoMapInitZod<Shape>>;
+      unique: CoValueUniqueness["uniqueness"];
+      owner: Owner;
+      resolve?: RefsToResolveStrict<
+        Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap,
+        R
+      >;
+    }) => Promise<Resolved<
+      Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap,
+      R
+    > | null>;
+
+    loadUnique<
+      const R extends RefsToResolve<
+        Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap
+      > = true,
+    >(
+      unique: CoValueUniqueness["uniqueness"],
+      ownerID: string,
+      options?: {
+        resolve?: RefsToResolveStrict<
+          Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap,
+          R
+        >;
+        loadAs?: Account | AnonymousJazzAgent;
+      },
+    ): Promise<Resolved<
+      Simplify<CoMapInstanceCoValuesNullable<Shape>> & CoMap,
+      R
+    > | null>;
+
     catchall<T extends z.core.$ZodType>(
       schema: T,
     ): CoMapSchema<Shape, z.core.$catchall<T>>;

package/src/tools/implementation/zodSchema/zodCo.ts

@@ -44,6 +44,12 @@ function enrichCoMapSchema<Shape extends z.core.$ZodLooseShape>(
     findUnique: (...args: any[]) => {
       return coSchema.findUnique(...args);
     },
+    upsertUnique: (...args: any[]) => {
+      return coSchema.upsertUnique(...args);
+    },
+    loadUnique: (...args: any[]) => {
+      return coSchema.loadUnique(...args);
+    },
     catchall: (index: z.core.$ZodType) => {
       return enrichCoMapSchema(baseCatchall(index));
     },

package/src/tools/subscribe/CoValueCoreSubscription.ts

@@ -10,22 +10,25 @@ export class CoValueCoreSubscription {
     public node: LocalNode,
     public id: string,
     public listener: (value: RawCoValue | "unavailable") => void,
+    public skipRetry?: boolean,
   ) {
     const entry = this.node.getCoValue(this.id as any);
 
     if (entry?.isAvailable()) {
       this.subscribe(entry.getCurrentContent());
     } else {
-      this.node.loadCoValueCore(this.id as any).then((value) => {
-        if (this.unsubscribed) return;
+      this.node
+        .loadCoValueCore(this.id as any, undefined, skipRetry)
+        .then((value) => {
+          if (this.unsubscribed) return;
 
-        if (value.isAvailable()) {
-          this.subscribe(value.getCurrentContent());
-        } else {
-          this.listener("unavailable");
-          this.subscribeToState();
-        }
-      });
+          if (value.isAvailable()) {
+            this.subscribe(value.getCurrentContent());
+          } else {
+            this.subscribeToState();
+            this.listener("unavailable");
+          }
+        });
     }
   }
 

package/src/tools/subscribe/SubscriptionScope.ts

@@ -44,34 +44,46 @@ export class SubscriptionScope<D extends CoValue> {
     resolve: RefsToResolve<D>,
     public id: ID<D>,
     public schema: RefEncoded<D>,
+    public skipRetry?: boolean,
   ) {
     this.resolve = resolve;
     this.value = { type: "unloaded", id };
 
     let lastUpdate: RawCoValue | "unavailable" | undefined;
-    this.subscription = new CoValueCoreSubscription(node, id, (value) => {
-      lastUpdate = value;
-
-      // Need all these checks because the migration can trigger new syncronous updates
-      //
-      // We want to:
-      // - Run the migration only once
-      // - Skip all the updates until the migration is done
-      // - Trigger handleUpdate only with the final value
-      if (!this.migrated && value !== "unavailable") {
-        if (this.migrating) {
+    this.subscription = new CoValueCoreSubscription(
+      node,
+      id,
+      (value) => {
+        lastUpdate = value;
+
+        if (skipRetry && value === "unavailable") {
+          this.handleUpdate(value);
+          this.destroy();
           return;
         }
 
-        this.migrating = true;
-        applyCoValueMigrations(instantiateRefEncoded(this.schema, value));
-        this.migrated = true;
-        this.handleUpdate(lastUpdate);
-        return;
-      }
+        // Need all these checks because the migration can trigger new syncronous updates
+        //
+        // We want to:
+        // - Run the migration only once
+        // - Skip all the updates until the migration is done
+        // - Trigger handleUpdate only with the final value
+        if (!this.migrated && value !== "unavailable") {
+          if (this.migrating) {
+            return;
+          }
+
+          this.migrating = true;
+          applyCoValueMigrations(instantiateRefEncoded(this.schema, value));
+          this.migrated = true;
+          this.handleUpdate(lastUpdate);
+          return;
+        }
 
-      this.handleUpdate(value);
-    });
+        this.handleUpdate(value);
+      },
+      skipRetry,
+    );
   }
 
   updateValue(value: SubscriptionValue<D, any>) {

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

@@ -688,6 +688,75 @@ describe("FileStream.loadAsBlob", async () => {
   });
 });
 
+describe("FileStream.loadAsBase64", async () => {
+  async function setup() {
+    const me = await Account.create({
+      creationProps: { name: "Hermes Puggington" },
+      crypto: Crypto,
+    });
+
+    const stream = FileStream.create({ owner: me });
+
+    stream.start({ mimeType: "text/plain" });
+
+    return { stream, me };
+  }
+
+  test("resolves only when the stream is ended", async () => {
+    const { stream, me } = await setup();
+    stream.push(new Uint8Array([1]));
+
+    const promise = FileStream.loadAsBase64(stream.id, { loadAs: me });
+
+    stream.push(new Uint8Array([2]));
+    stream.end();
+
+    const base64 = await promise;
+
+    // The promise resolves only when the stream is ended
+    // so we get a blob with all the chunks
+    expect(base64).toBe("AQI=");
+  });
+
+  test("resolves with a data URL if dataURL: true", async () => {
+    const { stream, me } = await setup();
+    stream.push(new Uint8Array([1]));
+
+    const promise = FileStream.loadAsBase64(stream.id, {
+      loadAs: me,
+      dataURL: true,
+    });
+
+    stream.push(new Uint8Array([2]));
+    stream.end();
+
+    const base64 = await promise;
+
+    // The promise resolves only when the stream is ended
+    // so we get a blob with all the chunks
+    expect(base64).toBe("data:text/plain;base64,AQI=");
+  });
+
+  test("resolves with a partial base64 if allowUnfinished: true", async () => {
+    const { stream, me } = await setup();
+    stream.push(new Uint8Array([1]));
+
+    const promise = FileStream.loadAsBase64(stream.id, {
+      loadAs: me,
+      allowUnfinished: true,
+    });
+
+    const base64 = await promise;
+
+    stream.push(new Uint8Array([2]));
+    stream.end();
+
+    // The promise resolves before the stream is ended
+    // so we get a blob only with the first chunk
+    expect(base64).toBe("AQ==");
+  });
+});
+
 describe("FileStream progress tracking", async () => {
   test("createFromBlob should report upload progress correctly", async () => {
     // Create 5MB test blob