graphddb 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",

package/dist/chunk-QQNP43JL.js

@@ -1,461 +0,0 @@
-import {
-  ChangeCaptureRegistry,
-  resolveModelClass
-} from "./chunk-6AIAHP3A.js";
-
-// src/cdc/prng.ts
-var SeededRandom = class {
-  state;
-  constructor(seed) {
-    this.state = seed >>> 0 || 2654435769;
-  }
-  /** Next float in [0, 1). */
-  next() {
-    this.state |= 0;
-    this.state = this.state + 1831565813 | 0;
-    let t = Math.imul(this.state ^ this.state >>> 15, 1 | this.state);
-    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
-    return ((t ^ t >>> 14) >>> 0) / 4294967296;
-  }
-  /** Integer in [min, max] inclusive. */
-  int(min, max) {
-    return min + Math.floor(this.next() * (max - min + 1));
-  }
-  /** Bernoulli trial: true with probability `p`. */
-  chance(p) {
-    if (p <= 0) return false;
-    if (p >= 1) return true;
-    return this.next() < p;
-  }
-  /** In-place Fisher–Yates shuffle, deterministic for the seed state. */
-  shuffle(items) {
-    for (let i = items.length - 1; i > 0; i--) {
-      const j = this.int(0, i);
-      const tmp = items[i];
-      items[i] = items[j];
-      items[j] = tmp;
-    }
-    return items;
-  }
-};
-function hashString(value) {
-  let h = 2166136261;
-  for (let i = 0; i < value.length; i++) {
-    h ^= value.charCodeAt(i);
-    h = Math.imul(h, 16777619);
-  }
-  return h >>> 0;
-}
-function shardIdFor(pk, shardCount) {
-  const index = hashString(pk) % shardCount;
-  return `shard-${String(index).padStart(4, "0")}`;
-}
-
-// src/cdc/emulator.ts
-function resolveToClass(model) {
-  try {
-    return resolveModelClass(model);
-  } catch {
-    return model;
-  }
-}
-var EPOCH = Date.parse("2020-01-01T00:00:00.000Z");
-var CdcEmulator = class {
-  mode;
-  clockMode;
-  batchSize;
-  maxRetries;
-  startingPosition;
-  shardCount;
-  seed;
-  rng;
-  faultSpec = {};
-  concurrentRecompute = null;
-  concurrentRecomputeHook = null;
-  /** Per-shard monotonic sequence counter. */
-  seqCounters = /* @__PURE__ */ new Map();
-  /** Per-shard delivery queue (queued/replay modes). */
-  queues = /* @__PURE__ */ new Map();
-  /** Per-shard last successfully checkpointed sequence number. */
-  checkpointMap = /* @__PURE__ */ new Map();
-  /**
-   * Per-shard set of acked sequence numbers (as ints) not yet folded into the
-   * checkpoint. The checkpoint advances over the contiguous prefix of acked
-   * sequences (ReportBatchItemFailures semantics): a sequence is checkpointed
-   * only once every sequence at or before it has been acked.
-   */
-  ackedSeqs = /* @__PURE__ */ new Map();
-  /** Per-shard count of sequences ever assigned, to bound the prefix scan. */
-  maxSeqSeen = /* @__PURE__ */ new Map();
-  /** Recorded event log (record mode and always, for replay()). */
-  log = [];
-  /** Dead-letter buffer. */
-  dlq = [];
-  handler = null;
-  /** Virtual clock (ms since EPOCH). */
-  clockMs = 0;
-  /** Pending async work from inline-mode captures, awaited by callers. */
-  inflight = Promise.resolve();
-  detachCapture = null;
-  models;
-  constructor(opts = {}) {
-    this.mode = opts.mode ?? "inline";
-    this.clockMode = opts.clock ?? (this.mode === "queued" ? "virtual" : "real");
-    this.batchSize = opts.batchSize ?? 100;
-    this.maxRetries = opts.maxRetries ?? 3;
-    this.startingPosition = opts.startingPosition ?? "TRIM_HORIZON";
-    this.shardCount = opts.shardCount ?? 8;
-    this.seed = opts.seed ?? 1;
-    this.rng = new SeededRandom(this.seed);
-    this.models = (opts.models ?? []).map(resolveToClass);
-    for (const model of this.models) {
-      ChangeCaptureRegistry.enableStream(model);
-    }
-    this.detachCapture = ChangeCaptureRegistry.register((record) => {
-      this.onRawWrite(record);
-    });
-  }
-  // ── seam → ChangeEvent mapping (spec §4, §5) ─────────────────────────────
-  onRawWrite(record) {
-    if (record.model && this.models.length > 0) {
-      const enabled = this.models.some((m) => m.name === record.model);
-      if (!enabled) return;
-    }
-    const event = this.toChangeEvent(record);
-    this.log.push(event);
-    if (this.mode === "record" || this.mode === "replay") {
-      return;
-    }
-    this.enqueue(event);
-    if (this.mode === "inline") {
-      this.inflight = this.inflight.then(() => this.pump());
-    }
-  }
-  toChangeEvent(record) {
-    const shardId = shardIdFor(record.keys.pk, this.shardCount);
-    const seq = (this.seqCounters.get(shardId) ?? 0) + 1;
-    this.seqCounters.set(shardId, seq);
-    this.maxSeqSeen.set(shardId, seq);
-    const eventName = this.deriveEventName(record);
-    const newImage = eventName === "REMOVE" ? void 0 : record.newItem ?? void 0;
-    const oldImage = record.oldItem ?? void 0;
-    return {
-      eventName,
-      table: record.table,
-      ...record.model ? { model: record.model } : {},
-      keys: { pk: record.keys.pk, sk: record.keys.sk },
-      ...oldImage ? { oldImage } : {},
-      ...newImage ? { newImage } : {},
-      approximateCreationTime: this.nowIso(),
-      sequenceNumber: String(seq).padStart(20, "0"),
-      shardId
-    };
-  }
-  /** Parse a zero-padded sequence string back to its integer value. */
-  seqToInt(seq) {
-    return Number.parseInt(seq, 10);
-  }
-  /** Render an integer sequence as the zero-padded string form. */
-  intToSeq(n) {
-    return String(n).padStart(20, "0");
-  }
-  /**
-   * Advance a shard's checkpoint over the contiguous prefix of acked sequence
-   * numbers. Starting just past the current checkpoint, consume every
-   * consecutive acked sequence; stop at the first gap (an un-acked sequence
-   * still pending redelivery). Consumed sequences are removed from the acked
-   * set to bound its size.
-   */
-  advanceCheckpoint(shardId) {
-    const acked = this.ackedSeqs.get(shardId);
-    if (!acked || acked.size === 0) return;
-    const current = this.checkpointMap.get(shardId);
-    let next = current === void 0 ? 0 : this.seqToInt(current);
-    const maxSeq = this.maxSeqSeen.get(shardId) ?? 0;
-    let advanced = false;
-    while (next + 1 <= maxSeq && acked.has(next + 1)) {
-      next += 1;
-      acked.delete(next);
-      advanced = true;
-    }
-    if (advanced) this.checkpointMap.set(shardId, this.intToSeq(next));
-  }
-  deriveEventName(record) {
-    if (record.op === "delete") return "REMOVE";
-    return record.oldItem ? "MODIFY" : "INSERT";
-  }
-  nowIso() {
-    if (this.clockMode === "virtual") {
-      return new Date(EPOCH + this.clockMs).toISOString();
-    }
-    return (/* @__PURE__ */ new Date()).toISOString();
-  }
-  // ── enqueue + delivery (spec §6) ─────────────────────────────────────────
-  enqueue(event) {
-    const queue = this.queues.get(event.shardId) ?? [];
-    let dueAt = this.clockMode === "virtual" ? this.clockMs : 0;
-    if (this.faultSpec.delay) {
-      const { min, max } = this.faultSpec.delay;
-      dueAt += this.rng.int(min, max);
-    }
-    queue.push({ event, dueAt, attempts: 0, droppedOnce: false });
-    this.queues.set(event.shardId, queue);
-  }
-  /**
-   * Deliver buffered, due records to the consumer, advancing per-shard
-   * checkpoints on success and redelivering failures. In `queued`/`replay`
-   * modes call this (or {@link advanceClock}) to drive delivery; `inline` calls
-   * it automatically after each capture.
-   */
-  async pump(maxBatches = Number.POSITIVE_INFINITY) {
-    if (!this.handler) return;
-    let delivered = 0;
-    let madeProgress = true;
-    while (madeProgress && delivered < maxBatches) {
-      madeProgress = false;
-      for (const shardId of [...this.queues.keys()]) {
-        const batch = this.collectBatch(shardId);
-        if (batch.length === 0) continue;
-        await this.deliverBatch(shardId, batch);
-        delivered += 1;
-        madeProgress = true;
-        if (delivered >= maxBatches) break;
-      }
-    }
-  }
-  /**
-   * Pull up to `batchSize` due records from a shard, preserving ascending
-   * sequence order (spec §6). When the `reorder` fault is on, the within-shard
-   * order is deliberately shuffled to exercise invariant detection.
-   */
-  collectBatch(shardId) {
-    const queue = this.queues.get(shardId);
-    if (!queue || queue.length === 0) return [];
-    const ready = [];
-    const now = this.clockMode === "virtual" ? this.clockMs : Number.POSITIVE_INFINITY;
-    const remaining = [];
-    for (const pd of queue) {
-      if (ready.length < this.batchSize && pd.dueAt <= now) {
-        ready.push(pd);
-      } else {
-        remaining.push(pd);
-      }
-    }
-    this.queues.set(shardId, remaining);
-    if (this.faultSpec.reorder && ready.length > 1) {
-      this.rng.shuffle(ready);
-    }
-    return ready;
-  }
-  async deliverBatch(shardId, pending) {
-    const delivered = [];
-    const droppedThisRound = [];
-    for (const pd of pending) {
-      if (!pd.droppedOnce && this.faultSpec.dropThenRedeliver && this.rng.chance(this.faultSpec.dropThenRedeliver)) {
-        pd.droppedOnce = true;
-        droppedThisRound.push(pd);
-        continue;
-      }
-      delivered.push(pd);
-      if (this.faultSpec.duplicate && this.rng.chance(this.faultSpec.duplicate)) {
-        delivered.push(pd);
-      }
-    }
-    if (droppedThisRound.length > 0) {
-      const queue = this.queues.get(shardId) ?? [];
-      queue.unshift(...droppedThisRound);
-      this.queues.set(shardId, queue);
-    }
-    if (delivered.length === 0) return;
-    const records = delivered.map((pd) => pd.event);
-    if (this.concurrentRecompute && this.concurrentRecomputeHook) {
-      for (const event of records) {
-        await this.concurrentRecomputeHook(this.concurrentRecompute, event);
-      }
-    }
-    const batch = { records };
-    const result = await this.handler(batch) ?? {};
-    const failures = new Set(result.batchItemFailures ?? []);
-    if (this.faultSpec.partialBatchFailure) {
-      for (const pd of delivered) {
-        if (this.rng.chance(this.faultSpec.partialBatchFailure)) {
-          failures.add(pd.event.sequenceNumber);
-        }
-      }
-    }
-    const requeue = [];
-    const seen = /* @__PURE__ */ new Set();
-    const acked = this.ackedSeqs.get(shardId) ?? /* @__PURE__ */ new Set();
-    for (const pd of delivered) {
-      const seq = pd.event.sequenceNumber;
-      if (failures.has(seq)) {
-        pd.attempts += 1;
-        if (pd.attempts > this.maxRetries) {
-          this.dlq.push(pd.event);
-        } else if (!seen.has(seq)) {
-          requeue.push(pd);
-          seen.add(seq);
-        }
-      } else {
-        acked.add(this.seqToInt(seq));
-      }
-    }
-    this.ackedSeqs.set(shardId, acked);
-    this.advanceCheckpoint(shardId);
-    if (requeue.length > 0) {
-      const queue = this.queues.get(shardId) ?? [];
-      requeue.sort(
-        (a, b) => a.event.sequenceNumber < b.event.sequenceNumber ? -1 : 1
-      );
-      queue.unshift(...requeue);
-      this.queues.set(shardId, queue);
-    }
-  }
-  // ── public API (spec §10) ────────────────────────────────────────────────
-  /** Register the consumer. Returns an unsubscribe handle. */
-  subscribe(handler) {
-    this.handler = handler;
-    if (this.startingPosition === "LATEST") {
-      this.queues.clear();
-    }
-    return () => {
-      if (this.handler === handler) this.handler = null;
-    };
-  }
-  /** Await any inline-mode async deliveries triggered by writes. */
-  async flush() {
-    await this.inflight;
-  }
-  /**
-   * Advance the virtual clock by `ms` and deliver records whose due-time has
-   * arrived (spec §7). Reproduces throttle T / sweep period / staleness S time
-   * behavior deterministically (AC4).
-   */
-  async advanceClock(ms) {
-    if (this.clockMode !== "virtual") {
-      throw new Error('advanceClock requires clock: "virtual"');
-    }
-    this.clockMs += ms;
-    await this.pump();
-  }
-  /** Current virtual time (ms since the emulator epoch). */
-  now() {
-    return this.clockMs;
-  }
-  /** Configure fault injection (spec §8). Merges into the current spec. */
-  fault(spec) {
-    this.faultSpec = { ...this.faultSpec, ...spec };
-  }
-  /**
-   * Force a recompute to race a mark for the given ref (spec §8, §7). The
-   * harness supplies the actual recompute via {@link onConcurrentRecompute};
-   * this records which ref to race and arms the hook.
-   */
-  injectConcurrentRecompute(ref) {
-    this.concurrentRecompute = ref;
-  }
-  /**
-   * Register the callback the emulator invokes (before each record reaches the
-   * consumer) when a concurrent recompute has been injected. This is how the
-   * test harness wires its recompute into the delivery race.
-   */
-  onConcurrentRecompute(hook) {
-    this.concurrentRecomputeHook = hook;
-  }
-  /** Snapshot the recorded event log (spec §10). */
-  record() {
-    return { seed: this.seed, events: this.log.map((e) => ({ ...e })) };
-  }
-  /**
-   * Replay an event log through the delivery pipeline, optionally shuffled and
-   * duplicated (spec §10, AC5). Used to prove **replay equivalence**: starting
-   * from any global order plus duplicates, a consumer that respects the
-   * per-shard ordering contract (spec §6) reaches a final aggregate equal to a
-   * full recompute from source.
-   *
-   * The shuffle models cross-shard reordering and at-least-once chaos at the
-   * delivery boundary. It must NOT, however, break the within-shard ordering
-   * guarantee that real DynamoDB Streams provides and that incremental
-   * aggregation depends on — so after shuffling/duplicating, each shard's queue
-   * is re-sorted into ascending original `sequenceNumber` order before delivery.
-   * The original `sequenceNumber` (assigned at record time) is preserved so it
-   * remains the source-of-truth ordering the consumer can rely on.
-   */
-  async replay(log, opts = {}) {
-    const replayRng = new SeededRandom(log.seed ?? this.seed);
-    let events = log.events.map((e) => ({ ...e }));
-    if (opts.shuffle) {
-      events = replayRng.shuffle(events);
-    }
-    const expanded = [];
-    for (const e of events) {
-      expanded.push(e);
-      if (opts.duplicate && replayRng.chance(opts.duplicate)) {
-        expanded.push({ ...e });
-      }
-    }
-    this.queues.clear();
-    this.seqCounters.clear();
-    this.ackedSeqs.clear();
-    this.maxSeqSeen.clear();
-    this.checkpointMap.clear();
-    for (const e of expanded) {
-      const shardId = shardIdFor(e.keys.pk, this.shardCount);
-      const resequenced = { ...e, shardId };
-      const queue = this.queues.get(shardId) ?? [];
-      queue.push({ event: resequenced, dueAt: 0, attempts: 0, droppedOnce: false });
-      this.queues.set(shardId, queue);
-      const seqInt = this.seqToInt(resequenced.sequenceNumber);
-      if (seqInt > (this.maxSeqSeen.get(shardId) ?? 0)) {
-        this.maxSeqSeen.set(shardId, seqInt);
-      }
-    }
-    for (const [shardId, queue] of this.queues) {
-      queue.sort(
-        (a, b) => a.event.sequenceNumber < b.event.sequenceNumber ? -1 : a.event.sequenceNumber > b.event.sequenceNumber ? 1 : 0
-      );
-      this.queues.set(shardId, queue);
-    }
-    await this.pump();
-  }
-  /** Per-shard checkpoints (last acked sequence number). */
-  checkpoints() {
-    return Object.fromEntries(this.checkpointMap);
-  }
-  /** Dead-lettered events (exceeded maxRetries). */
-  deadLetters() {
-    return this.dlq.map((e) => ({ ...e }));
-  }
-  /** Reset delivery state and re-seed (keeps the subscription + model opt-in). */
-  reset() {
-    this.seqCounters.clear();
-    this.queues.clear();
-    this.checkpointMap.clear();
-    this.ackedSeqs.clear();
-    this.maxSeqSeen.clear();
-    this.log = [];
-    this.dlq = [];
-    this.clockMs = 0;
-    this.inflight = Promise.resolve();
-    this.faultSpec = {};
-    this.concurrentRecompute = null;
-    this.rng = new SeededRandom(this.seed);
-  }
-  /** Tear down: detach from the core seam and disable model streaming. */
-  close() {
-    this.detachCapture?.();
-    this.detachCapture = null;
-    for (const model of this.models) {
-      ChangeCaptureRegistry.disableStream(model);
-    }
-    this.handler = null;
-  }
-};
-function createCdcEmulator(opts = {}) {
-  return new CdcEmulator(opts);
-}
-
-export {
-  CdcEmulator,
-  createCdcEmulator
-};