jazz-tools 0.16.6 → 0.17.0

package/src/media/index.ts

@@ -0,0 +1,61 @@
+import type { ImageDefinition } from "jazz-tools";
+import {
+  CreateImageOptions,
+  SourceType,
+  createImageFactory,
+} from "./create-image.js";
+
+export { highestResAvailable, loadImage, loadImageBySize } from "./utils.js";
+export { createImageFactory };
+
+/**
+ * Creates an ImageDefinition from an image file or blob with built-in UX features.
+ *
+ * This function creates a specialized CoValue for managing images in Jazz applications.
+ * It supports blurry placeholders, built-in resizing, and progressive loading patterns.
+ *
+ * @returns Promise that resolves to an ImageDefinition
+ *
+ * @example
+ * ```ts
+ * import { createImage } from "jazz-tools/media";
+ *
+ * // Create an image from a file input
+ * async function handleFileUpload(event: React.ChangeEvent<HTMLInputElement>) {
+ *   const file = event.target.files?.[0];
+ *   if (file) {
+ *     // Creates ImageDefinition with a blurry placeholder, limited to 1024px
+ *     // on the longest side, and multiple resolutions automatically
+ *     const image = await createImage(file, {
+ *       owner: me._owner,
+ *       maxSize: 1024,
+ *       placeholder: "blur",
+ *       progressive: true,
+ *     });
+ *
+ *     // Store the image in your application data
+ *     me.profile.image = image;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // React Native example
+ * import { createImage } from "jazz-tools/media";
+ *
+ * async function uploadImageFromCamera(imagePath: string) {
+ *   const image = await createImage(imagePath, {
+ *     maxSize: 800,
+ *     placeholder: "blur",
+ *     progressive: false,
+ *   });
+ *
+ *   return image;
+ * }
+ * ```
+ */
+export declare function createImage(
+  imageBlobOrFile: SourceType,
+  options?: CreateImageOptions,
+): Promise<ImageDefinition>;

package/src/media/utils.test.ts

@@ -0,0 +1,327 @@
+import { Account, FileStream, ImageDefinition } from "jazz-tools";
+import { highestResAvailable, loadImageBySize } from "jazz-tools/media";
+import { createJazzTestAccount, setupJazzTestSync } from "jazz-tools/testing";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const createFileStream = (account: any, blobSize?: number) => {
+  return FileStream.createFromBlob(
+    new Blob([new Uint8Array(blobSize || 1)], { type: "image/png" }),
+    {
+      owner: account,
+    },
+  );
+};
+
+describe("highestResAvailable", async () => {
+  let account: Account;
+
+  beforeEach(async () => {
+    account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+    vi.spyOn(Account, "getMe").mockReturnValue(account);
+    await setupJazzTestSync();
+  });
+
+  it("returns original if progressive is false", async () => {
+    const original = await createFileStream(account._owner);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [1920, 1080],
+        progressive: false,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["1920x1080"] = original;
+
+    const result = highestResAvailable(imageDef, 256, 256);
+    expect(result?.image.id).toBe(original.id);
+  });
+
+  it("returns original if progressive is true but no resizes present", async () => {
+    const original = await createFileStream(account._owner, 1);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [1920, 1080],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["1920x1080"] = original;
+
+    const result = highestResAvailable(imageDef, 256, 256);
+    expect(result?.image.id).toBe(original.id);
+  });
+
+  it("returns closest available resize if progressive is true", async () => {
+    const original = await createFileStream(account._owner);
+    const resize256 = await createFileStream(account._owner, 1);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [1920, 1080],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["1920x1080"] = original;
+    imageDef["256x256"] = resize256;
+
+    const result = highestResAvailable(imageDef, 256, 256);
+    expect(result?.image.id).toBe(resize256.id);
+  });
+
+  it("returns original if wanted size matches original size", async () => {
+    const original = await createFileStream(account._owner);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [1024, 1024],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["1024x1024"] = original;
+
+    const result = highestResAvailable(imageDef, 1024, 1024);
+    expect(result?.image.id).toBe(original.id);
+  });
+
+  it("returns best fit among multiple resizes", async () => {
+    const original = await createFileStream(account._owner);
+    const resize256 = await createFileStream(account._owner, 1);
+    const resize1024 = await createFileStream(account._owner, 1);
+    const resize2048 = await createFileStream(account._owner, 1);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [2048, 2048],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["256x256"] = resize256;
+    imageDef["1024x1024"] = resize1024;
+    imageDef["2048x2048"] = resize2048;
+
+    // Closest to 900x900 is 1024
+    const result = highestResAvailable(imageDef, 900, 900);
+    expect(result?.image.id).toBe(resize1024.id);
+  });
+
+  it("returns the best fit resolution", async () => {
+    const original = await createFileStream(account._owner, 1);
+    const resize256 = await createFileStream(account._owner, 1);
+    const resize2048 = await createFileStream(account._owner, 1);
+    // 1024 is not loaded yet
+    const resize1024 = FileStream.create({ owner: account._owner });
+    resize1024.start({ mimeType: "image/jpeg" });
+    // Don't end resize1024, so it has no chunks
+
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [2048, 2048],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+    imageDef["256x256"] = resize256;
+    imageDef["1024x1024"] = resize1024;
+    imageDef["2048x2048"] = resize2048;
+
+    // Closest to 900x900 is 1024
+    const result = highestResAvailable(imageDef, 900, 900);
+    expect(result?.image.id).toBe(resize2048.id);
+  });
+
+  it("returns original if no resizes are loaded (missing chunks)", async () => {
+    const original = await createFileStream(account._owner);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [256, 256],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["256x256"] = original;
+    // 1024 is not loaded yet
+    const resize1024 = FileStream.create({ owner: account._owner });
+    resize1024.start({ mimeType: "image/jpeg" });
+    // Don't end resize1024, so it has no chunks
+    imageDef["1024x1024"] = resize1024;
+
+    const result = highestResAvailable(imageDef, 1024, 1024);
+    // Only original is valid
+    expect(result?.image.id).toBe(original.id);
+  });
+
+  it("returns the first loaded resize if original is not loaded yet(missing chunks)", async () => {
+    const original = FileStream.create({ owner: account._owner });
+    original.start({ mimeType: "image/jpeg" });
+    // Don't call .end(), so it has no chunks
+
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [300, 300],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["256x256"] = await createFileStream(account._owner, 1);
+
+    const result = highestResAvailable(imageDef, 1024, 1024);
+    // Only original is valid
+    expect(result?.image.id).toBe(imageDef["256x256"].id);
+  });
+
+  it("returns the highest resolution if no good match is found", async () => {
+    const original = await createFileStream(account._owner, 1);
+
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [300, 300],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+
+    imageDef["256x256"] = await createFileStream(account._owner, 1);
+    imageDef["300x300"] = original;
+
+    const result = highestResAvailable(imageDef, 1024, 1024);
+    expect(result?.image.id).toBe(original.id);
+  });
+});
+
+describe("loadImageBySize", async () => {
+  let account: Account;
+  beforeEach(async () => {
+    account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+    vi.spyOn(Account, "getMe").mockReturnValue(account);
+    await setupJazzTestSync();
+  });
+
+  const createImageDef = async (
+    sizes: Array<[number, number]>,
+    progressive = true,
+  ) => {
+    if (sizes.length === 0) throw new Error("sizes array must not be empty");
+
+    const originalSize = sizes[sizes.length - 1]!;
+    sizes = sizes.slice(0, -1);
+
+    const original = await createFileStream(account, 1);
+    // Ensure sizes array is not empty
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize,
+        progressive,
+        original,
+      },
+      { owner: account },
+    );
+    imageDef[`${originalSize[0]}x${originalSize[1]}`] = original;
+
+    for (const size of sizes) {
+      if (!size) continue;
+      const [w, h] = size;
+      imageDef[`${w}x${h}`] = await createFileStream(account, 1);
+    }
+    return imageDef;
+  };
+
+  it("returns original if progressive is false", async () => {
+    const imageDef = await createImageDef([[1920, 1080]], false);
+    const result = await loadImageBySize(imageDef, 256, 256);
+    expect(result?.image.id).toBe(imageDef["1920x1080"]!.id);
+  });
+
+  it("returns null if no sizes are available", async () => {
+    const original = await createFileStream(account._owner, 1);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [1920, 1080],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+    const result = await loadImageBySize(imageDef, 256, 256);
+    expect(result).toBeNull();
+  });
+
+  it("returns the closest available resize if progressive is true", async () => {
+    const imageDef = await createImageDef([
+      [256, 256],
+      [1920, 1080],
+    ]);
+    const result = await loadImageBySize(imageDef.id, 256, 256);
+    expect(result?.image.id).toBe(imageDef["256x256"]!.id);
+    expect(result?.width).toBe(256);
+    expect(result?.height).toBe(256);
+  });
+
+  it("returns the best fit among multiple resizes", async () => {
+    const imageDef = await createImageDef([
+      [256, 256],
+      [1024, 1024],
+      [2048, 2048],
+    ]);
+    const result = await loadImageBySize(imageDef, 900, 900);
+    expect(result?.image.id).toBe(imageDef["1024x1024"]!.id);
+    expect(result?.width).toBe(1024);
+    expect(result?.height).toBe(1024);
+  });
+
+  it("returns the highest resolution if no good match is found", async () => {
+    const imageDef = await createImageDef([
+      [256, 256],
+      [300, 300],
+    ]);
+    const result = await loadImageBySize(imageDef, 1024, 1024);
+    expect(result?.image.id).toBe(imageDef["300x300"]!.id);
+    expect(result?.width).toBe(300);
+    expect(result?.height).toBe(300);
+  });
+
+  it("returns null if the best target is not loaded", async () => {
+    const original = await createFileStream(account._owner, 1);
+    const imageDef = ImageDefinition.create(
+      {
+        originalSize: [256, 256],
+        progressive: true,
+        original,
+      },
+      { owner: account._owner },
+    );
+    // No resizes added
+    const result = await loadImageBySize(imageDef, 1024, 1024);
+    expect(result).toBeNull();
+  });
+
+  it("returns the correct size when wanted size matches available size exactly", async () => {
+    const imageDef = await createImageDef([
+      [512, 512],
+      [1024, 1024],
+    ]);
+    const result = await loadImageBySize(imageDef, 1024, 1024);
+    expect(result?.image.id).toBe(imageDef["1024x1024"]!.id);
+    expect(result?.width).toBe(1024);
+    expect(result?.height).toBe(1024);
+  });
+});

package/src/media/utils.ts

@@ -0,0 +1,202 @@
+import type { CoID } from "cojson";
+import { Account, FileStream, ImageDefinition } from "jazz-tools";
+
+export function highestResAvailable(
+  image: ImageDefinition,
+  wantedWidth: number,
+  wantedHeight: number,
+): { width: number; height: number; image: FileStream } | null {
+  const availableSizes: [number, number, string][] = image._raw
+    .keys()
+    .filter((key) => /^\d+x\d+$/.test(key))
+    .map((key) => {
+      const [w, h] = key.split("x").map(Number) as [number, number];
+      return [w, h, key];
+    });
+
+  if (availableSizes.length === 0) {
+    return image.original
+      ? {
+          width: image.originalSize[0],
+          height: image.originalSize[1],
+          image: image.original,
+        }
+      : null;
+  }
+
+  const sortedSizes = availableSizes
+    .map((size) => {
+      return {
+        size,
+        match: sizesMatchWanted(size[0], size[1], wantedWidth, wantedHeight),
+        isLoaded: isLoaded(image._raw.get(size[2]) as CoID<any> | undefined),
+      };
+    })
+    .sort((a, b) => a.match - b.match);
+
+  // We try to find the better already loaded image
+  // note: `toReversed` is not available in react-native.
+  const bestLoaded = [...sortedSizes]
+    .reverse()
+    .find((el) => el.isLoaded && image[el.size[2]]?.getChunks());
+
+  // if I can't find a good match, let's use the highest resolution
+  const bestTarget =
+    sortedSizes.find((el) => el.match > 0.95) || sortedSizes.at(-1);
+
+  // if the best target is already loaded, we are done
+  if (image[bestTarget!.size[2]]?.getChunks()) {
+    return image[bestTarget!.size[2]]
+      ? {
+          width: bestTarget!.size[0],
+          height: bestTarget!.size[1],
+          image: image[bestTarget!.size[2]]!,
+        }
+      : null;
+  }
+
+  // if the best already loaded is not the best target
+  // let's trigger the load of the best target
+  if (bestLoaded) {
+    image[bestTarget!.size[2]]?.getChunks();
+    return image[bestLoaded.size[2]]
+      ? {
+          width: bestLoaded.size[0],
+          height: bestLoaded.size[1],
+          image: image[bestLoaded.size[2]]!,
+        }
+      : null;
+  }
+
+  // if nothing is loaded, then start fetching all the images till the best
+  for (let size of sortedSizes) {
+    if (size.match <= bestTarget!.match) {
+      image[size.size[2]]?.getChunks();
+    }
+  }
+
+  return null;
+}
+
+function sizesMatchWanted(
+  w: number,
+  h: number,
+  wantedW: number,
+  wantedH: number,
+): number {
+  const area1 = w * h;
+  const area2 = wantedW * wantedH;
+
+  const areaRatio = area1 / area2;
+
+  // // Below 0.95 means the image is too small, we don't want to upscale it
+  // if (areaRatio < 0.95) {
+  //   return 9999;
+  // }
+
+  return areaRatio;
+}
+
+function isLoaded(id: CoID<any> | null | undefined): boolean {
+  if (!id) {
+    return false;
+  }
+
+  return !!Account.getMe()._raw.core.node.getLoaded(id);
+}
+
+export async function loadImage(
+  imageOrId: ImageDefinition | string,
+): Promise<{ width: number; height: number; image: FileStream } | null> {
+  if (typeof imageOrId === "string") {
+    const image = await ImageDefinition.load(imageOrId, {
+      resolve: {
+        original: true,
+      },
+    });
+
+    if (image === null || image.original === null) {
+      return null;
+    }
+
+    return {
+      width: image.originalSize[0],
+      height: image.originalSize[1],
+      image: image.original,
+    };
+  }
+
+  await imageOrId.ensureLoaded({
+    resolve: {
+      original: true,
+    },
+  });
+
+  if (!imageOrId.original) {
+    console.warn("Unable to find the original image");
+    return null;
+  }
+
+  return {
+    width: imageOrId.originalSize[0],
+    height: imageOrId.originalSize[1],
+    image: imageOrId.original,
+  };
+}
+
+export async function loadImageBySize(
+  imageOrId: ImageDefinition | string,
+  wantedWidth: number,
+  wantedHeight: number,
+): Promise<{ width: number; height: number; image: FileStream } | null> {
+  const image =
+    typeof imageOrId === "string"
+      ? await ImageDefinition.load(imageOrId)
+      : imageOrId;
+
+  if (image === null) {
+    return null;
+  }
+
+  if (image.progressive === false) {
+    return loadImage(imageOrId);
+  }
+
+  const availableSizes: [number, number, string][] = image._raw
+    .keys()
+    .filter((key) => /^\d+x\d+$/.test(key))
+    .map((key) => {
+      const [w, h] = key.split("x").map(Number) as [number, number];
+      return [w, h, key];
+    });
+
+  if (availableSizes.length === 0) {
+    return null;
+  }
+
+  const sortedSizes = availableSizes
+    .map((size) => ({
+      size,
+      match: sizesMatchWanted(size[0], size[1], wantedWidth, wantedHeight),
+    }))
+    .sort((a, b) => a.match - b.match);
+
+  const bestTarget =
+    sortedSizes.find((el) => el.match > 0.95) || sortedSizes.at(-1)!;
+
+  const deepLoaded = await ImageDefinition.load(image.id, {
+    resolve: {
+      [bestTarget.size[2]]: true,
+    },
+  });
+
+  if (deepLoaded === null || deepLoaded[bestTarget.size[2]] === undefined) {
+    return null;
+  }
+
+  return {
+    width: bestTarget.size[0],
+    height: bestTarget.size[1],
+    image: deepLoaded[bestTarget.size[2]]!,
+  };
+}

package/src/react/index.ts

@@ -12,5 +12,4 @@ export {
 export { createInviteLink, parseInviteLink } from "jazz-tools/browser";
 
 export * from "./auth/auth.js";
-export * from "./media.js";
-export { createImage } from "jazz-tools/browser-media-images";
+export * from "./media/image.js";