@loro-dev/flock 4.4.5 → 4.5.1

package/src/index.ts

@@ -258,6 +258,20 @@ function normalizePeerId(peerId?: string): string {
   return peerId;
 }
 
+const SYNC_TXN_CALLBACK_ERROR = "Flock.txn callback must be synchronous";
+
+function isAsyncCallback(callback: Function): boolean {
+  return callback.constructor?.name === "AsyncFunction";
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as PromiseLike<unknown>).then === "function"
+  );
+}
+
 type EncodableVersionVectorEntry = {
   peer: string;
   peerBytes: Uint8Array;
@@ -523,6 +537,16 @@ function normalizePruneBefore(
   return pruneTombstonesBefore;
 }
 
+function normalizeMutationNow(now?: number | null): number | undefined {
+  if (now === undefined || now === null) {
+    return undefined;
+  }
+  if (typeof now !== "number" || !Number.isFinite(now)) {
+    throw new TypeError("now must be a finite number");
+  }
+  return now;
+}
+
 function decodeVersionVectorFromRaw(raw: unknown): VersionVector {
   if (raw === null || typeof raw !== "object") {
     return {};
@@ -554,13 +578,34 @@ function decodeVersionVectorFromRaw(raw: unknown): VersionVector {
 }
 
 function encodeBound(bound?: ScanBound): Record<string, unknown> | undefined {
-  if (!bound) {
+  if (bound === undefined) {
     return undefined;
   }
+  if (!bound || typeof bound !== "object") {
+    throw new TypeError("scan bound must be an object");
+  }
   if (bound.kind === "unbounded") {
     return { kind: "unbounded" };
   }
-  return { kind: bound.kind, key: bound.key.slice() };
+  if (bound.kind !== "inclusive" && bound.kind !== "exclusive") {
+    throw new TypeError(
+      "scan bound kind must be inclusive, exclusive, or unbounded",
+    );
+  }
+  if (!Array.isArray(bound.key)) {
+    throw new TypeError("scan bound key must be a key array");
+  }
+  return { kind: bound.kind, key: cloneKey(bound.key) };
+}
+
+function normalizeScanPrefix(prefix: unknown): KeyPart[] | undefined {
+  if (prefix === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(prefix)) {
+    throw new TypeError("scan prefix must be a key array");
+  }
+  return cloneKey(prefix as KeyPart[]);
 }
 
 function decodeEntryInfo(raw: unknown): EntryInfo | undefined {
@@ -634,18 +679,163 @@ function normalizeRawEventPayload(
   return result;
 }
 
-const structuredCloneFn: (<T>(value: T) => T) | undefined = (
-  globalThis as typeof globalThis & { structuredClone?: <T>(value: T) => T }
-).structuredClone;
+const JSON_SERIALIZATION_ERROR = "Value is not JSON serializable";
+const JSON_SERIALIZATION_WARNING_PREFIX = "[flock] JSON value normalized:";
+
+function warnJsonNormalization(message: string): void {
+  try {
+    console.warn(`${JSON_SERIALIZATION_WARNING_PREFIX} ${message}`);
+  } catch {
+    // Ignore console failures so value normalization never becomes a write error.
+  }
+}
+
+function normalizeInvalidJsonValue(message: string): null {
+  warnJsonNormalization(message);
+  return null;
+}
+
+function normalizeJsonValue(
+  value: unknown,
+  seen: WeakSet<object>,
+  inObjectEntry = false,
+): unknown {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return normalizeInvalidJsonValue("non-finite number stored as null");
+  }
+  if (value === undefined) {
+    return inObjectEntry ? undefined : null;
+  }
+  if (typeof value === "function" || typeof value === "symbol") {
+    warnJsonNormalization(`${typeof value} value omitted`);
+    return inObjectEntry ? undefined : null;
+  }
+  if (typeof value === "bigint") {
+    if (
+      value <= BigInt(Number.MAX_SAFE_INTEGER) &&
+      value >= BigInt(Number.MIN_SAFE_INTEGER)
+    ) {
+      return Number(value);
+    }
+    return normalizeInvalidJsonValue(
+      "bigint exceeds JavaScript safe integer range and was stored as null",
+    );
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const toJson = (value as { toJSON?: unknown }).toJSON;
+  if (typeof toJson === "function") {
+    try {
+      return normalizeJsonValue(toJson.call(value), seen, inObjectEntry);
+    } catch {
+      return normalizeInvalidJsonValue("toJSON threw and value was stored as null");
+    }
+  }
+
+  if (seen.has(value)) {
+    return normalizeInvalidJsonValue("circular reference stored as null");
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = value.map((item) => {
+      const normalized = normalizeJsonValue(item, seen);
+      return normalized === undefined ? null : normalized;
+    });
+    seen.delete(value);
+    return result;
+  }
+
+  let keys: string[];
+  try {
+    keys = Object.keys(value);
+  } catch {
+    seen.delete(value);
+    return normalizeInvalidJsonValue("object keys could not be read and value was stored as null");
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const key of keys) {
+    let rawValue: unknown;
+    try {
+      rawValue = (value as Record<string, unknown>)[key];
+    } catch {
+      result[key] = normalizeInvalidJsonValue(
+        "object property could not be read and was stored as null",
+      );
+      continue;
+    }
+    const normalized = normalizeJsonValue(
+      rawValue,
+      seen,
+      true,
+    );
+    if (normalized !== undefined) {
+      result[key] = normalized;
+    }
+  }
+  seen.delete(value);
+  return result;
+}
+
+function validateJsonPart(value: unknown): unknown {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError(JSON_SERIALIZATION_ERROR);
+  }
+  if (
+    value === undefined ||
+    typeof value === "function" ||
+    typeof value === "symbol" ||
+    typeof value === "bigint"
+  ) {
+    throw new TypeError(JSON_SERIALIZATION_ERROR);
+  }
+  return value;
+}
+
+function stringifyJson(value: unknown): string {
+  const normalized = normalizeJsonValue(value, new WeakSet<object>());
+  return JSON.stringify(normalized) ?? "null";
+}
+
+function stringifyStrictJson(value: unknown): string {
+  const encoded = JSON.stringify(value, (_key, part) =>
+    validateJsonPart(part),
+  );
+  if (encoded === undefined) {
+    throw new TypeError(JSON_SERIALIZATION_ERROR);
+  }
+  return encoded;
+}
+
+function stringifyStoredJson(value: Value | undefined): string {
+  return value === undefined ? "null" : stringifyJson(value);
+}
 
 function cloneJson<T>(value: T): T {
   if (value === undefined) {
     return value;
   }
-  if (structuredCloneFn) {
-    return structuredCloneFn(value);
+  return JSON.parse(stringifyJson(value)) as T;
+}
+
+function cloneStrictJson<T>(value: T): T {
+  if (value === undefined) {
+    return value;
   }
-  return JSON.parse(JSON.stringify(value)) as T;
+  return JSON.parse(stringifyStrictJson(value)) as T;
+}
+
+function cloneStoredJson(value: Value | undefined): Value {
+  return value === undefined ? null : cloneJson(value);
+}
+
+function cloneKey(key: KeyPart[]): KeyPart[] {
+  if (!Array.isArray(key)) {
+    throw new TypeError("key must be an array");
+  }
+  return cloneStrictJson(key) as KeyPart[];
 }
 
 function parseKeyString(key: string): KeyPart[] {
@@ -725,8 +915,11 @@ function createExportPayload(record: ExportRecord): ExportPayload {
   return payload;
 }
 
-function createPutPayload(value: Value, metadata?: MetadataMap): ExportPayload {
-  const payload: ExportPayload = { data: cloneJson(value) };
+function createPutPayload(
+  value: Value | undefined,
+  metadata?: MetadataMap,
+): ExportPayload {
+  const payload: ExportPayload = { data: cloneStoredJson(value) };
   const cleanMetadata = cloneMetadata(metadata);
   if (cleanMetadata !== undefined) {
     payload.metadata = cleanMetadata;
@@ -804,6 +997,21 @@ function normalizeImportDecision(
   return { accept: true };
 }
 
+function payloadFromImportDecision(
+  decision: ImportDecision,
+): ImportPayload | undefined {
+  if (!decision || typeof decision !== "object") {
+    return undefined;
+  }
+  if ("accept" in decision) {
+    return undefined;
+  }
+  if ("data" in decision || "metadata" in decision) {
+    return decision as ImportPayload;
+  }
+  return undefined;
+}
+
 function decodeImportReport(raw: unknown): ImportReport {
   if (!raw || typeof raw !== "object") {
     return { accepted: 0, skipped: [] };
@@ -828,10 +1036,31 @@ function cloneBundle(bundle: ExportBundle): ExportBundle {
   return next;
 }
 
+function isVersionVectorEntry(value: unknown): value is VersionVectorEntry {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as VersionVectorEntry).physicalTime === "number" &&
+    Number.isFinite((value as VersionVectorEntry).physicalTime) &&
+    typeof (value as VersionVectorEntry).logicalCounter === "number" &&
+    Number.isFinite((value as VersionVectorEntry).logicalCounter)
+  );
+}
+
+function isVersionVectorLike(value: unknown): value is VersionVector {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.keys(value).length > 0 &&
+    Object.values(value).every(isVersionVectorEntry)
+  );
+}
+
 function isExportOptions(value: unknown): value is ExportOptions {
   return (
     typeof value === "object" &&
     value !== null &&
+    !isVersionVectorLike(value) &&
     (Object.prototype.hasOwnProperty.call(value, "hooks") ||
       Object.prototype.hasOwnProperty.call(value, "from") ||
       Object.prototype.hasOwnProperty.call(value, "pruneTombstonesBefore") ||
@@ -894,34 +1123,50 @@ export class Flock {
 
   private putWithMetaInternal(
     key: KeyPart[],
-    value: Value,
+    value: Value | undefined,
     metadata?: MetadataMap,
     now?: number,
+  ): void {
+    this.putWithMetaPrepared(
+      cloneKey(key),
+      value,
+      metadata,
+      normalizeMutationNow(now),
+    );
+  }
+
+  private putWithMetaPrepared(
+    cleanKey: KeyPart[],
+    value: Value | undefined,
+    metadata: MetadataMap | undefined,
+    cleanNow: number | undefined,
   ): void {
     const metadataClone = cloneMetadata(metadata);
     put_with_meta_ffi(
       this.inner,
-      key,
-      JSON.stringify(value),
+      cleanKey,
+      stringifyStoredJson(value),
       metadataClone,
-      now,
+      cleanNow,
     );
   }
 
   private async putWithMetaWithHooks(
     key: KeyPart[],
-    value: Value,
+    value: Value | undefined,
     options: PutWithMetaOptions,
   ): Promise<void> {
+    const cleanKey = cloneKey(key);
+    const cleanNow = normalizeMutationNow(options.now);
     const basePayload = createPutPayload(value, options.metadata);
     const transform = options.hooks?.transform;
     if (!transform) {
-      this.putWithMetaInternal(key, value, options.metadata, options.now);
+      this.putWithMetaPrepared(cleanKey, value, options.metadata, cleanNow);
       return;
     }
     const workingPayload = clonePayload(basePayload);
     const transformed = await transform(
-      { key: key.slice(), now: options.now },
+      { key: cleanKey.slice(), now: cleanNow },
       workingPayload,
     );
     const finalPayload = mergePayload(
@@ -932,11 +1177,11 @@ export class Flock {
     if (finalValue === undefined) {
       throw new TypeError("putWithMeta requires a data value");
     }
-    this.putWithMetaInternal(
-      key,
+    this.putWithMetaPrepared(
+      cleanKey,
       finalValue,
       finalPayload.metadata,
-      options.now,
+      cleanNow,
     );
   }
 
@@ -946,13 +1191,18 @@ export class Flock {
    * @param value
    * @param now
    */
-  put(key: KeyPart[], value: Value, now?: number): void {
-    put_json_ffi(this.inner, key, JSON.stringify(value), now);
+  put(key: KeyPart[], value: Value | undefined, now?: number): void {
+    put_json_ffi(
+      this.inner,
+      cloneKey(key),
+      stringifyStoredJson(value),
+      normalizeMutationNow(now),
+    );
   }
 
   putWithMeta(
     key: KeyPart[],
-    value: Value,
+    value: Value | undefined,
     options?: PutWithMetaOptions,
   ): void | Promise<void> {
     const opts = options ?? {};
@@ -962,7 +1212,7 @@ export class Flock {
     this.putWithMetaInternal(key, value, opts.metadata, opts.now);
   }
 
-  set(key: KeyPart[], value: Value, now?: number): void {
+  set(key: KeyPart[], value: Value | undefined, now?: number): void {
     this.put(key, value, now);
   }
 
@@ -972,7 +1222,7 @@ export class Flock {
    * @param now
    */
   delete(key: KeyPart[], now?: number): void {
-    delete_ffi(this.inner, key, now);
+    delete_ffi(this.inner, cloneKey(key), normalizeMutationNow(now));
   }
 
   get(key: KeyPart[]): Value | undefined {
@@ -1119,7 +1369,10 @@ export class Flock {
           delete working.entries[key];
           continue;
         }
-        working.entries[key] = buildRecord(record.c, basePayload);
+        working.entries[key] = buildRecord(
+          record.c,
+          mergePayload(basePayload, payloadFromImportDecision(decision)),
+        );
       }
     }
     const coreReport = this.importJsonInternal(working);
@@ -1176,18 +1429,26 @@ export class Flock {
   }
 
   putMvr(key: KeyPart[], value: Value, now?: number): void {
-    put_mvr_ffi(this.inner, key, JSON.stringify(value), now);
+    put_mvr_ffi(
+      this.inner,
+      cloneKey(key),
+      stringifyJson(value),
+      normalizeMutationNow(now),
+    );
   }
 
   getMvr(key: KeyPart[]): Value[] {
-    const raw = get_mvr_ffi(this.inner, key);
+    const raw = get_mvr_ffi(this.inner, cloneKey(key));
     return Array.isArray(raw) ? (raw as Value[]) : [];
   }
 
   scan(options: ScanOptions = {}): ScanRow[] {
+    if (!options || typeof options !== "object") {
+      throw new TypeError("scan options must be an object");
+    }
     const start = encodeBound(options.start);
     const end = encodeBound(options.end);
-    const prefix = options.prefix ? options.prefix.slice() : undefined;
+    const prefix = normalizeScanPrefix(options.prefix);
     const rows = scan_ffi(this.inner, start, end, prefix) as
       | RawScanRow[]
       | undefined;
@@ -1337,9 +1598,19 @@ export class Flock {
         "Cannot start transaction while autoDebounceCommit is active",
       );
     }
+    if (isAsyncCallback(callback)) {
+      throw new TypeError(SYNC_TXN_CALLBACK_ERROR);
+    }
     txn_begin_ffi(this.inner);
     try {
       const result = callback();
+      if (isThenable(result)) {
+        void Promise.resolve(result).catch(() => {});
+        if (is_in_txn_ffi(this.inner)) {
+          txn_rollback_ffi(this.inner);
+        }
+        throw new TypeError(SYNC_TXN_CALLBACK_ERROR);
+      }
       txn_commit_ffi(this.inner);
       return result;
     } catch (e) {

package/src/moonbit.d.ts

@@ -47,6 +47,12 @@ export type Int64 = bigint & { [__brand]: "Int64" };
  */
 export type UInt64 = bigint & { [__brand]: "UInt64" };
 
+/**
+ * Backed directly by `bigint`.
+ * Valid `V128` values are in the unsigned 128-bit range `[0, 2^128)`.
+ */
+export type V128 = bigint & { [__brand]: "V128" };
+
 export type String = string;
 
 export type Bytes = Uint8Array;