jazz-tools 0.16.5 → 0.17.0

package/src/media/index.browser.ts

@@ -0,0 +1,150 @@
+import { Account, FileStream, Group, ImageDefinition } from "jazz-tools";
+import { CreateImageOptions, createImageFactory } from "./create-image.js";
+
+export { highestResAvailable, loadImage, loadImageBySize } from "./utils.js";
+
+export { createImageFactory };
+
+export async function createImage(
+  imageBlobOrFile: Blob | File | string,
+  options?: CreateImageOptions,
+) {
+  return createImageFactory({
+    createFileStreamFromSource,
+    getImageSize,
+    getPlaceholderBase64,
+    resize,
+  })(imageBlobOrFile, options || {});
+}
+
+//  Image Manipulations
+async function createFileStreamFromSource(
+  imageBlobOrFile: Blob | File | string,
+  owner?: Account | Group,
+): Promise<FileStream> {
+  if (typeof imageBlobOrFile === "string") {
+    throw new Error(
+      "createFileStreamFromSource(string) is not supported on this platform",
+    );
+  }
+
+  return FileStream.createFromBlob(imageBlobOrFile, owner);
+}
+
+// using createImageBitmap is ~10x slower than Image object
+// Image object: 640 milliseconds
+// createImageBitmap: 8128 milliseconds
+function getImageFromBlob(blob: Blob): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => {
+      resolve(img);
+      URL.revokeObjectURL(img.src);
+    };
+    img.onerror = () => {
+      reject(new Error("Failed to load image"));
+      URL.revokeObjectURL(img.src);
+    };
+    img.src = URL.createObjectURL(blob);
+  });
+}
+
+async function getImageSize(
+  imageBlobOrFile: Blob | File | string,
+): Promise<{ width: number; height: number }> {
+  if (typeof imageBlobOrFile === "string") {
+    throw new Error("getImageSize(string) is not supported on browser");
+  }
+
+  const image = await getImageFromBlob(imageBlobOrFile);
+
+  return { width: image.width, height: image.height };
+}
+
+async function getPlaceholderBase64(
+  imageBlobOrFile: Blob | File | string,
+): Promise<string> {
+  if (typeof imageBlobOrFile === "string") {
+    throw new Error("getPlaceholderBase64(string) is not supported on browser");
+  }
+
+  const image = await getImageFromBlob(imageBlobOrFile);
+
+  const { width, height } = resizeDimensionsKeepingAspectRatio(
+    image.width,
+    image.height,
+    8,
+  );
+
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+
+  const ctx = canvas.getContext("2d");
+
+  if (!ctx) {
+    throw new Error("Failed to get context");
+  }
+
+  ctx.drawImage(image, 0, 0, width, height);
+
+  return canvas.toDataURL("image/png");
+}
+
+const resizeDimensionsKeepingAspectRatio = (
+  width: number,
+  height: number,
+  maxSize: number,
+): { width: number; height: number } => {
+  if (width <= maxSize && height <= maxSize) {
+    return { width, height };
+  }
+
+  const aspectRatio = width / height;
+
+  if (width >= height) {
+    return { width: maxSize, height: Math.round(maxSize / aspectRatio) };
+  } else {
+    return { width: Math.round(maxSize * aspectRatio), height: maxSize };
+  }
+};
+
+async function resize(
+  imageBlobOrFile: Blob | File | string,
+  width: number,
+  height: number,
+): Promise<Blob> {
+  if (typeof imageBlobOrFile === "string") {
+    throw new Error("resize(string) is not supported on browser");
+  }
+
+  const mimeType = imageBlobOrFile.type;
+
+  const image = await getImageFromBlob(imageBlobOrFile);
+
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+
+  const ctx = canvas.getContext("2d");
+
+  if (!ctx) {
+    throw new Error("Failed to get context");
+  }
+
+  ctx.drawImage(image, 0, 0, width, height);
+
+  return new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (!blob) {
+          reject(new Error("Failed to convert canvas to blob"));
+          return;
+        }
+        resolve(blob);
+      },
+      mimeType,
+      0.8,
+    );
+  });
+}

package/src/media/index.native.ts

@@ -0,0 +1,153 @@
+import ImageResizer from "@bam.tech/react-native-image-resizer";
+import type { Account, Group, ImageDefinition } from "jazz-tools";
+import { FileStream } from "jazz-tools";
+import { Image } from "react-native";
+import {
+  CreateImageOptions,
+  SourceType,
+  createImageFactory,
+} from "./create-image.js";
+
+export { highestResAvailable, loadImage, loadImageBySize } from "./utils.js";
+export { createImageFactory };
+
+export async function createImage(
+  imageBlobOrFile: Blob | File | string,
+  options?: CreateImageOptions,
+) {
+  return createImageFactory({
+    getImageSize,
+    getPlaceholderBase64,
+    createFileStreamFromSource,
+    resize,
+  })(imageBlobOrFile, options || {});
+}
+
+async function getImageSize(
+  filePath: SourceType,
+): Promise<{ width: number; height: number }> {
+  if (typeof filePath !== "string") {
+    throw new Error(
+      "createImage(Blob | File) is not supported on this platform",
+    );
+  }
+
+  const { width, height } = await Image.getSize(filePath);
+
+  return { width, height };
+}
+
+async function getPlaceholderBase64(filePath: SourceType): Promise<string> {
+  if (typeof filePath !== "string") {
+    throw new Error(
+      "createImage(Blob | File) is not supported on this platform",
+    );
+  }
+
+  if (typeof ImageResizer === "undefined" || ImageResizer === null) {
+    throw new Error(
+      "ImageResizer is not installed, please run `npm install @bam.tech/react-native-image-resizer`",
+    );
+  }
+
+  const { uri } = await ImageResizer.createResizedImage(
+    filePath,
+    8,
+    8,
+    "PNG",
+    100,
+  );
+
+  return imageUrlToBase64(uri);
+}
+
+async function resize(
+  filePath: SourceType,
+  width: number,
+  height: number,
+): Promise<string> {
+  if (typeof filePath !== "string") {
+    throw new Error(
+      "createImage(Blob | File) is not supported on this platform",
+    );
+  }
+
+  if (typeof ImageResizer === "undefined" || ImageResizer === null) {
+    throw new Error(
+      "ImageResizer is not installed, please run `npm install @bam.tech/react-native-image-resizer`",
+    );
+  }
+
+  const mimeType = await getMimeType(filePath);
+
+  const { uri } = await ImageResizer.createResizedImage(
+    filePath,
+    width,
+    height,
+    contentTypeToFormat(mimeType),
+    80,
+  );
+
+  return uri;
+}
+
+function getMimeType(filePath: string): Promise<string> {
+  return fetch(filePath)
+    .then((res) => res.blob())
+    .then((blob) => blob.type);
+}
+
+function contentTypeToFormat(contentType: string) {
+  if (contentType.includes("image/png")) return "PNG";
+  if (contentType.includes("image/jpeg")) return "JPEG";
+  if (contentType.includes("image/webp")) return "WEBP";
+  return "PNG";
+}
+
+export async function createFileStreamFromSource(
+  filePath: SourceType,
+  owner?: Account | Group,
+): Promise<FileStream> {
+  if (typeof filePath !== "string") {
+    throw new Error(
+      "createImage(Blob | File) is not supported on this platform",
+    );
+  }
+
+  const blob = await fetch(filePath).then((res) => res.blob());
+  const arrayBuffer = await toArrayBuffer(blob);
+
+  return FileStream.createFromArrayBuffer(arrayBuffer, blob.type, undefined, {
+    owner,
+  });
+}
+
+// TODO: look for more efficient way to do this as React Native hasn't blob.arrayBuffer()
+function toArrayBuffer(blob: Blob): Promise<ArrayBuffer> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      resolve(reader.result as ArrayBuffer);
+    };
+    reader.onerror = (error) => {
+      reject(error);
+    };
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+async function imageUrlToBase64(url: string): Promise<string> {
+  const response = await fetch(url);
+  const blob = await response.blob();
+  return new Promise((onSuccess, onError) => {
+    try {
+      const reader = new FileReader();
+      reader.onload = function () {
+        onSuccess(reader.result as string);
+      };
+      reader.readAsDataURL(blob);
+    } catch (e) {
+      onError(e);
+    }
+  });
+}

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);
+  });
+});