@loro-dev/flock 1.0.0

package/src/index.ts

@@ -0,0 +1,758 @@
+import {
+  newFlock,
+  get_ffi,
+  put_json_ffi,
+  put_with_meta_ffi,
+  delete_ffi,
+  merge,
+  set_peer_id,
+  export_json_ffi,
+  import_json_ffi,
+  version_ffi,
+  get_max_physical_time_ffi,
+  peer_id_ffi,
+  kv_to_json_ffi,
+  digest_hex_ffi,
+  put_mvr_ffi,
+  get_mvr_ffi,
+  scan_ffi,
+  subscribe_ffi,
+  check_consistency_ffi,
+  check_invariants_ffi,
+  from_json_ffi,
+} from "./_moon_flock";
+
+type RawVersionVector = Record<string, [number, number]>;
+type RawScanRow = { key: KeyPart[]; raw: ExportRecord; value?: Value };
+type RawEventPayload = { data?: Value; metadata?: MetadataMap };
+type RawEventEntry = {
+  key?: KeyPart[];
+  value?: Value;
+  metadata?: MetadataMap;
+  payload?: RawEventPayload;
+};
+type RawEventBatch = { source?: string; events?: RawEventEntry[] };
+
+type MaybePromise<T> = T | Promise<T>;
+
+type ExportOptions = {
+  from?: VersionVector;
+  hooks?: ExportHooks;
+};
+
+type ImportOptions = {
+  bundle: ExportBundle;
+  hooks?: ImportHooks;
+};
+
+type RawImportReport = {
+  accepted?: number;
+  skipped?: Array<{ key?: KeyPart[]; reason?: string }>;
+};
+
+export type VersionVectorEntry = {
+  physicalTime: number;
+  logicalCounter: number;
+};
+
+export type VersionVector = Record<string, VersionVectorEntry>;
+
+export type Value =
+  | string
+  | number
+  | boolean
+  | null
+  | Array<Value>
+  | { [key: string]: Value };
+
+export type KeyPart = Value;
+
+export type MetadataMap = Record<string, unknown>;
+
+export type ExportRecord = {
+  c: string;
+  d?: Value;
+  m?: MetadataMap;
+};
+
+export type ExportBundle = Record<string, ExportRecord>;
+
+export type EntryClock = {
+  physicalTime: number;
+  logicalCounter: number;
+  peerIdHex: string;
+  peerId: Uint8Array;
+};
+
+export type ExportPayload = {
+  data?: Value;
+  metadata?: MetadataMap;
+};
+
+export type ExportHookContext = {
+  key: KeyPart[];
+  clock: EntryClock;
+  raw: ExportRecord;
+};
+
+export type ExportHooks = {
+  transform?: (
+    context: ExportHookContext,
+    payload: ExportPayload,
+  ) => MaybePromise<ExportPayload | void>;
+};
+
+export type ImportPayload = ExportPayload;
+
+export type ImportHookContext = ExportHookContext;
+
+export type ImportAccept = {
+  accept: true;
+};
+
+export type ImportSkip = {
+  accept: false;
+  reason: string;
+};
+
+export type ImportDecision = ImportAccept | ImportSkip | ImportPayload | void;
+
+export type ImportHooks = {
+  preprocess?: (
+    context: ImportHookContext,
+    payload: ImportPayload,
+  ) => MaybePromise<ImportDecision>;
+};
+
+export type ImportReport = {
+  accepted: number;
+  skipped: Array<{ key: KeyPart[]; reason: string }>;
+};
+
+export type PutPayload = ExportPayload;
+
+export type PutHookContext = {
+  key: KeyPart[];
+  now?: number;
+};
+
+export type PutHooks = {
+  transform?: (
+    context: PutHookContext,
+    payload: PutPayload,
+  ) => MaybePromise<PutPayload | void>;
+};
+
+export type PutWithMetaOptions = {
+  metadata?: MetadataMap;
+  now?: number;
+  hooks?: PutHooks;
+};
+
+export type ScanBound =
+  | { kind: "inclusive"; key: KeyPart[] }
+  | { kind: "exclusive"; key: KeyPart[] }
+  | { kind: "unbounded" };
+
+export type ScanOptions = {
+  start?: ScanBound;
+  end?: ScanBound;
+  prefix?: KeyPart[];
+};
+
+export type ScanRow = {
+  key: KeyPart[];
+  raw: ExportRecord;
+  value?: Value;
+};
+
+export type EventPayload = ExportPayload;
+
+export type Event = {
+  key: KeyPart[];
+  value?: Value;
+  metadata?: MetadataMap;
+  payload: EventPayload;
+};
+
+export type EventBatch = {
+  source: string;
+  events: Event[];
+};
+
+function bytesToHex(bytes: Uint8Array): string {
+  let hex = "";
+  for (let i = 0; i < bytes.length; i += 1) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new TypeError("peerId hex must have even length");
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i += 1) {
+    const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new TypeError("peerId hex contains invalid characters");
+    }
+    bytes[i] = byte;
+  }
+  return bytes;
+}
+
+function createRandomPeerId(): Uint8Array {
+  const id = new Uint8Array(32);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(id);
+  } else {
+    for (let i = 0; i < 32; i += 1) {
+      id[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  return id;
+}
+
+function normalizePeerId(peerId?: Uint8Array): Uint8Array {
+  if (peerId === undefined) {
+    return createRandomPeerId();
+  }
+  if (!(peerId instanceof Uint8Array)) {
+    throw new TypeError("peerId must be a Uint8Array");
+  }
+  return new Uint8Array(peerId);
+}
+
+function encodeVersionVector(vv?: VersionVector): RawVersionVector | undefined {
+  if (!vv) {
+    return undefined;
+  }
+  const raw: RawVersionVector = {};
+  for (const [peer, entry] of Object.entries(vv)) {
+    if (!entry) {
+      continue;
+    }
+    const { physicalTime, logicalCounter } = entry;
+    if (typeof physicalTime !== "number" || Number.isNaN(physicalTime)) {
+      continue;
+    }
+    if (!Number.isFinite(logicalCounter)) {
+      continue;
+    }
+    raw[peer] = [physicalTime, Math.trunc(logicalCounter)];
+  }
+  return raw;
+}
+
+function decodeVersionVector(raw: unknown): VersionVector {
+  if (raw === null || typeof raw !== "object") {
+    return {};
+  }
+  const result: VersionVector = {};
+  for (const [peer, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!Array.isArray(value) || value.length < 2) {
+      continue;
+    }
+    const [physicalTime, logicalCounter] = value;
+    if (typeof physicalTime !== "number" || !Number.isFinite(physicalTime)) {
+      continue;
+    }
+    if (typeof logicalCounter !== "number" || !Number.isFinite(logicalCounter)) {
+      continue;
+    }
+    result[peer] = {
+      physicalTime,
+      logicalCounter: Math.trunc(logicalCounter),
+    };
+  }
+  return result;
+}
+
+function encodeBound(bound?: ScanBound): Record<string, unknown> | undefined {
+  if (!bound) {
+    return undefined;
+  }
+  if (bound.kind === "unbounded") {
+    return { kind: "unbounded" };
+  }
+  return { kind: bound.kind, key: bound.key.slice() };
+}
+
+function decodeEventBatch(raw: unknown): EventBatch {
+  if (!raw || typeof raw !== "object") {
+    return { source: "local", events: [] };
+  }
+  const batch = raw as RawEventBatch;
+  const source = typeof batch.source === "string" ? batch.source : "local";
+  const eventsRaw = Array.isArray(batch.events) ? batch.events : [];
+  const events = eventsRaw
+    .filter((entry): entry is RawEventEntry => Boolean(entry))
+    .map((entry) => buildEvent(entry));
+  return { source, events };
+}
+
+function buildEvent(entry: RawEventEntry): Event {
+  const key = Array.isArray(entry.key) ? entry.key : [];
+  const payload = buildEventPayload(entry);
+  return {
+    key,
+    value: payload.data,
+    metadata: cloneMetadata(payload.metadata),
+    payload,
+  };
+}
+
+function buildEventPayload(entry: RawEventEntry): EventPayload {
+  const base: ExportPayload = {};
+  if ("value" in entry) {
+    base.data = cloneJson(entry.value as Value);
+  }
+  const entryMetadata = cloneMetadata(entry.metadata);
+  if (entryMetadata !== undefined) {
+    base.metadata = entryMetadata;
+  }
+  const update = normalizeRawEventPayload(entry.payload);
+  return mergePayload(base, update);
+}
+
+function normalizeRawEventPayload(
+  payload: RawEventPayload | undefined,
+): ExportPayload | undefined {
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+  const result: ExportPayload = {};
+  if ("data" in payload) {
+    result.data = cloneJson(payload.data as Value);
+  }
+  const metadata = cloneMetadata(payload.metadata);
+  if (metadata !== undefined) {
+    result.metadata = metadata;
+  }
+  return result;
+}
+
+const structuredCloneFn: (<T>(value: T) => T) | undefined =
+  (globalThis as typeof globalThis & { structuredClone?: <T>(value: T) => T }).structuredClone;
+
+function cloneJson<T>(value: T): T {
+  if (value === undefined) {
+    return value;
+  }
+  if (structuredCloneFn) {
+    return structuredCloneFn(value);
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function parseKeyString(key: string): KeyPart[] {
+  try {
+    const parsed = JSON.parse(key);
+    return Array.isArray(parsed) ? (parsed as KeyPart[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function cloneMetadata(metadata: unknown): MetadataMap | undefined {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return undefined;
+  }
+  return cloneJson(metadata as MetadataMap);
+}
+
+function decodeClock(record: ExportRecord): EntryClock {
+  const [physicalRaw, logicalRaw, peerHexRaw] = record.c.split(",");
+  const physicalTime = Number(physicalRaw);
+  const logicalCounter = Number(logicalRaw);
+  const peerIdHex = peerHexRaw ?? "";
+  let peerId: Uint8Array;
+  try {
+    peerId = hexToBytes(peerIdHex);
+  } catch {
+    peerId = new Uint8Array();
+  }
+  return {
+    physicalTime: Number.isFinite(physicalTime) ? physicalTime : 0,
+    logicalCounter: Number.isFinite(logicalCounter)
+      ? Math.trunc(logicalCounter)
+      : 0,
+    peerIdHex,
+    peerId,
+  };
+}
+
+function createExportPayload(record: ExportRecord): ExportPayload {
+  const payload: ExportPayload = {};
+  if (record.d !== undefined) {
+    payload.data = cloneJson(record.d);
+  }
+  const metadata = cloneMetadata(record.m);
+  if (metadata !== undefined) {
+    payload.metadata = metadata;
+  }
+  return payload;
+}
+
+function createPutPayload(
+  value: Value,
+  metadata?: MetadataMap,
+): ExportPayload {
+  const payload: ExportPayload = { data: cloneJson(value) };
+  const cleanMetadata = cloneMetadata(metadata);
+  if (cleanMetadata !== undefined) {
+    payload.metadata = cleanMetadata;
+  }
+  return payload;
+}
+
+function assignPayload(
+  target: ExportPayload,
+  source?: ExportPayload | void,
+): void {
+  if (!source || typeof source !== "object") {
+    return;
+  }
+  if ("data" in source) {
+    const value = source.data;
+    target.data = value === undefined ? undefined : cloneJson(value);
+  }
+  if ("metadata" in source) {
+    target.metadata = cloneMetadata(source.metadata);
+  }
+}
+
+function clonePayload(payload: ExportPayload | undefined): ExportPayload {
+  const result: ExportPayload = {};
+  assignPayload(result, payload);
+  return result;
+}
+
+function mergePayload(
+  base: ExportPayload,
+  update?: ExportPayload | void,
+): ExportPayload {
+  const result = clonePayload(base);
+  assignPayload(result, update);
+  return result;
+}
+
+function buildRecord(clock: string, payload: ExportPayload): ExportRecord {
+  const record: ExportRecord = { c: clock };
+  if (payload.data !== undefined) {
+    record.d = cloneJson(payload.data);
+  }
+  const metadata = cloneMetadata(payload.metadata);
+  if (metadata !== undefined) {
+    record.m = metadata;
+  }
+  return record;
+}
+
+function cloneRecord(record: ExportRecord): ExportRecord {
+  return buildRecord(record.c, createExportPayload(record));
+}
+
+function buildContext(key: string, record: ExportRecord): ExportHookContext {
+  return {
+    key: parseKeyString(key),
+    clock: decodeClock(record),
+    raw: cloneRecord(record),
+  };
+}
+
+function normalizeImportDecision(
+  decision: ImportDecision,
+): ImportAccept | ImportSkip {
+  if (!decision || typeof decision !== "object") {
+    return { accept: true };
+  }
+  if ("accept" in decision) {
+    const typed = decision as ImportAccept | ImportSkip;
+    if (typed.accept === false) {
+      return { accept: false, reason: typed.reason ?? "rejected" };
+    }
+    return { accept: true };
+  }
+  return { accept: true };
+}
+
+function decodeImportReport(raw: unknown): ImportReport {
+  if (!raw || typeof raw !== "object") {
+    return { accepted: 0, skipped: [] };
+  }
+  const report = raw as RawImportReport;
+  const accepted = typeof report.accepted === "number" ? report.accepted : 0;
+  const skippedRaw = Array.isArray(report.skipped) ? report.skipped : [];
+  const skipped = skippedRaw.map((entry) => {
+    const key = entry && Array.isArray(entry.key) ? entry.key : [];
+    const reason =
+      entry && typeof entry.reason === "string" ? entry.reason : "unknown";
+    return { key, reason };
+  });
+  return { accepted, skipped };
+}
+
+function cloneBundle(bundle: ExportBundle): ExportBundle {
+  const next: ExportBundle = {};
+  for (const [key, record] of Object.entries(bundle)) {
+    next[key] = cloneRecord(record);
+  }
+  return next;
+}
+
+function isExportOptions(value: unknown): value is ExportOptions {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (Object.prototype.hasOwnProperty.call(value, "hooks") ||
+      Object.prototype.hasOwnProperty.call(value, "from"))
+  );
+}
+
+function isImportOptions(value: unknown): value is ImportOptions {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.prototype.hasOwnProperty.call(value, "bundle")
+  );
+}
+
+export class Flock {
+  private inner: ReturnType<typeof newFlock>;
+
+  constructor(peerId?: Uint8Array) {
+    this.inner = newFlock(normalizePeerId(peerId));
+  }
+
+  private static fromInner(inner: ReturnType<typeof newFlock>): Flock {
+    const flock = new Flock();
+    flock.inner = inner;
+    return flock;
+  }
+
+  static fromJson(bundle: ExportBundle, peerId: Uint8Array): Flock {
+    const inner = from_json_ffi(bundle, bytesToHex(normalizePeerId(peerId)));
+    return Flock.fromInner(inner as ReturnType<typeof newFlock>);
+  }
+
+  static checkConsistency(a: Flock, b: Flock): boolean {
+    return Boolean(check_consistency_ffi(a.inner, b.inner));
+  }
+
+  checkInvariants(): void {
+    check_invariants_ffi(this.inner);
+  }
+
+  setPeerId(peerId: Uint8Array): void {
+    set_peer_id(this.inner, normalizePeerId(peerId));
+  }
+
+  private putWithMetaInternal(
+    key: KeyPart[],
+    value: Value,
+    metadata?: MetadataMap,
+    now?: number,
+  ): void {
+    const clonedValue = cloneJson(value);
+    const metadataClone = cloneMetadata(metadata);
+    put_with_meta_ffi(this.inner, key, clonedValue, metadataClone, now);
+  }
+
+  private async putWithMetaWithHooks(
+    key: KeyPart[],
+    value: Value,
+    options: PutWithMetaOptions,
+  ): Promise<void> {
+    const basePayload = createPutPayload(value, options.metadata);
+    const transform = options.hooks?.transform;
+    if (!transform) {
+      this.putWithMetaInternal(key, value, options.metadata, options.now);
+      return;
+    }
+    await transform(
+      { key: key.slice(), now: options.now },
+      clonePayload(basePayload),
+    );
+    const finalValue = basePayload.data;
+    if (finalValue === undefined) {
+      throw new TypeError("putWithMeta requires a data value");
+    }
+    this.putWithMetaInternal(key, finalValue, basePayload.metadata, options.now);
+  }
+
+  put(key: KeyPart[], value: Value, now?: number): void {
+    put_json_ffi(this.inner, key, value, now);
+  }
+
+  putWithMeta(key: KeyPart[], value: Value, options?: PutWithMetaOptions): void | Promise<void> {
+    const opts = options ?? {};
+    if (opts.hooks?.transform) {
+      return this.putWithMetaWithHooks(key, value, opts);
+    }
+    this.putWithMetaInternal(key, value, opts.metadata, opts.now);
+  }
+
+  set(key: KeyPart[], value: Value, now?: number): void {
+    this.put(key, value, now);
+  }
+
+  delete(key: KeyPart[], now?: number): void {
+    delete_ffi(this.inner, key, now);
+  }
+
+  get(key: KeyPart[]): Value | undefined {
+    return get_ffi(this.inner, key) as Value | undefined;
+  }
+
+  merge(other: Flock): void {
+    merge(this.inner, other.inner);
+  }
+
+  version(): VersionVector {
+    return decodeVersionVector(version_ffi(this.inner));
+  }
+
+  private exportJsonInternal(from?: VersionVector): ExportBundle {
+    return export_json_ffi(this.inner, encodeVersionVector(from)) as ExportBundle;
+  }
+
+  private async exportJsonWithHooks(options: ExportOptions): Promise<ExportBundle> {
+    const base = this.exportJsonInternal(options.from);
+    const transform = options.hooks?.transform;
+    if (!transform) {
+      return base;
+    }
+    const result: ExportBundle = {};
+    for (const [key, record] of Object.entries(base)) {
+      const context = buildContext(key, record);
+      const basePayload = createExportPayload(record);
+      const transformed = await transform(context, clonePayload(basePayload));
+      const finalPayload = mergePayload(basePayload, transformed);
+      result[key] = buildRecord(record.c, finalPayload);
+    }
+    return result;
+  }
+
+  exportJson(): ExportBundle;
+  exportJson(from: VersionVector): ExportBundle;
+  exportJson(options: ExportOptions): Promise<ExportBundle>;
+  exportJson(
+    arg?: VersionVector | ExportOptions,
+  ): ExportBundle | Promise<ExportBundle> {
+    if (arg === undefined) {
+      return this.exportJsonInternal();
+    }
+    if (isExportOptions(arg)) {
+      return this.exportJsonWithHooks(arg);
+    }
+    return this.exportJsonInternal(arg);
+  }
+
+  private importJsonInternal(bundle: ExportBundle): ImportReport {
+    const report = import_json_ffi(this.inner, bundle) as RawImportReport | undefined;
+    return decodeImportReport(report);
+  }
+
+  private async importJsonWithHooks(options: ImportOptions): Promise<ImportReport> {
+    const preprocess = options.hooks?.preprocess;
+    const working = preprocess ? cloneBundle(options.bundle) : options.bundle;
+    const skippedByHooks: Array<{ key: KeyPart[]; reason: string }> = [];
+    if (preprocess) {
+      for (const key of Object.keys(working)) {
+        const record = working[key];
+        if (!record) {
+          continue;
+        }
+        const context = buildContext(key, record);
+        const basePayload = createExportPayload(record);
+        const decision = await preprocess(context, clonePayload(basePayload));
+        const normalized = normalizeImportDecision(decision);
+        if (!normalized.accept) {
+          skippedByHooks.push({ key: context.key, reason: normalized.reason });
+          delete working[key];
+          continue;
+        }
+        working[key] = buildRecord(record.c, basePayload);
+      }
+    }
+    const coreReport = this.importJsonInternal(working);
+    return {
+      accepted: coreReport.accepted,
+      skipped: skippedByHooks.concat(coreReport.skipped),
+    };
+  }
+
+  importJson(bundle: ExportBundle): ImportReport;
+  importJson(options: ImportOptions): Promise<ImportReport>;
+  importJson(
+    arg: ExportBundle | ImportOptions,
+  ): ImportReport | Promise<ImportReport> {
+    if (isImportOptions(arg)) {
+      return this.importJsonWithHooks(arg);
+    }
+    return this.importJsonInternal(arg);
+  }
+
+  getMaxPhysicalTime(): number {
+    return Number(get_max_physical_time_ffi(this.inner));
+  }
+
+  peerId(): Uint8Array {
+    const hex = peer_id_ffi(this.inner);
+    if (typeof hex !== "string") {
+      throw new TypeError("peerId ffi returned unexpected value");
+    }
+    return hexToBytes(hex);
+  }
+
+  digest(): string {
+    const hex = digest_hex_ffi(this.inner);
+    if (typeof hex !== "string") {
+      throw new TypeError("digest ffi returned unexpected value");
+    }
+    return hex;
+  }
+
+  kvToJson(): ExportBundle {
+    return kv_to_json_ffi(this.inner) as ExportBundle;
+  }
+
+  putMvr(key: KeyPart[], value: Value, now?: number): void {
+    put_mvr_ffi(this.inner, key, value, now);
+  }
+
+  getMvr(key: KeyPart[]): Value[] {
+    const raw = get_mvr_ffi(this.inner, key);
+    return Array.isArray(raw) ? (raw as Value[]) : [];
+  }
+
+  scan(options: ScanOptions = {}): ScanRow[] {
+    const start = encodeBound(options.start);
+    const end = encodeBound(options.end);
+    const prefix = options.prefix ? options.prefix.slice() : undefined;
+    const rows = scan_ffi(this.inner, start, end, prefix) as RawScanRow[] | undefined;
+    if (!Array.isArray(rows)) {
+      return [];
+    }
+    return rows
+      .filter((row): row is RawScanRow => Boolean(row))
+      .map((row) => ({
+        key: Array.isArray(row.key) ? row.key : [],
+        raw: row.raw,
+        value: row.value,
+      }));
+  }
+
+  subscribe(listener: (batch: EventBatch) => void): () => void {
+    const unsubscribe = subscribe_ffi(this.inner, (payload: unknown) => {
+      listener(decodeEventBatch(payload));
+    });
+    if (typeof unsubscribe !== "function") {
+      throw new TypeError("subscribe ffi did not return a function");
+    }
+    return unsubscribe as () => void;
+  }
+}