@rxferrix/client 0.0.0-stage → 0.2.0

package/src/bytes.ts

@@ -0,0 +1,57 @@
+/**
+ * Binary values: `rxferrix::Bytes` travels (and is stored) as `{ $bytes: "<base64>" }`, which is also its generated
+ * TypeScript type. These helpers convert between that form and `Uint8Array`.
+ *
+ * ```ts
+ * await client.mutation(api.files.save_thumbnail, { id, thumb: bytesToJson(new Uint8Array(png)) });
+ * const doc = await client.query(api.files.get, { id });
+ * const png: Uint8Array = bytesFromJson(doc.thumb);
+ * ```
+ */
+
+/** The JSON form of `rxferrix::Bytes`: standard, padded base64. */
+export type Bytes = { $bytes: string };
+
+const CHUNK = 0x8000;
+
+/** Wrap binary data as `{ $bytes: "<base64>" }` (for args and documents). */
+export function bytesToJson(data: Uint8Array | ArrayBuffer | ArrayBufferView): Bytes {
+  const bytes =
+    data instanceof Uint8Array
+      ? data
+      : ArrayBuffer.isView(data)
+        ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+        : new Uint8Array(data);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return { $bytes: btoa(binary) };
+}
+
+/** The bytes of a `{ $bytes: "<base64>" }` value (from a query result or document). Throws a `TypeError` otherwise. */
+export function bytesFromJson(value: Bytes): Uint8Array {
+  if (!isBytes(value)) {
+    throw new TypeError("expected bytes as { $bytes: string }");
+  }
+  let binary: string;
+  try {
+    binary = atob(value.$bytes);
+  } catch {
+    throw new TypeError("`$bytes` is not valid base64");
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+
+/** True for a value in the `{ $bytes: string }` form (an object with exactly that key). */
+export function isBytes(value: unknown): value is Bytes {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  return keys.length === 1 && keys[0] === "$bytes" && typeof (value as Bytes).$bytes === "string";
+}

package/src/canonical.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical JSON: `JSON.stringify` with object keys sorted recursively. Two arg objects that are structurally equal
+ * produce the same string, regardless of key insertion order. `undefined` object values are dropped, as in JSON.
+ */
+export function canonicalJSON(value: unknown): string {
+  return JSON.stringify(sortKeys(value)) ?? "null";
+}
+
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== "object") return value;
+  if (typeof (value as { toJSON?: unknown }).toJSON === "function") {
+    return sortKeys((value as { toJSON: () => unknown }).toJSON());
+  }
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value).sort()) {
+    const v = (value as Record<string, unknown>)[key];
+    if (v === undefined || typeof v === "function" || typeof v === "symbol") continue;
+    out[key] = sortKeys(v);
+  }
+  return out;
+}
+
+/** The client-side identity of a query: `udfPath + canonicalJSON(args)`. */
+export type QueryToken = string;
+
+export function queryToken(udfPath: string, args: Record<string, unknown>): QueryToken {
+  return udfPath + canonicalJSON(args);
+}
+
+/** Structural equality for JSON values (as produced by `JSON.parse`). */
+export function jsonEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") {
+    // NaN never appears in JSON; plain === suffices for primitives.
+    return false;
+  }
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) if (!jsonEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (Array.isArray(b)) return false;
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const aKeys = Object.keys(ao);
+  if (aKeys.length !== Object.keys(bo).length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(bo, k) || !jsonEqual(ao[k], bo[k])) return false;
+  }
+  return true;
+}
+
+/** Normalizes user-supplied args: `undefined` becomes `{}`; anything else must be a plain object. */
+export function normalizeArgs(args: unknown): Record<string, unknown> {
+  if (args === undefined || args === null) return {};
+  if (typeof args !== "object" || Array.isArray(args)) {
+    throw new TypeError(`RxFerrix function args must be an object, got ${Array.isArray(args) ? "array" : typeof args}`);
+  }
+  return args as Record<string, unknown>;
+}