@noy-db/core 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -21,10 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Collection: () => Collection,
+  CollectionIndexes: () => CollectionIndexes,
   Compartment: () => Compartment,
   ConflictError: () => ConflictError,
   DecryptionError: () => DecryptionError,
   InvalidKeyError: () => InvalidKeyError,
+  Lru: () => Lru,
   NOYDB_BACKUP_VERSION: () => NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION: () => NOYDB_FORMAT_VERSION,
   NOYDB_KEYRING_VERSION: () => NOYDB_KEYRING_VERSION,
@@ -35,6 +37,7 @@ __export(index_exports, {
   Noydb: () => Noydb,
   NoydbError: () => NoydbError,
   PermissionDeniedError: () => PermissionDeniedError,
+  Query: () => Query,
   ReadOnlyError: () => ReadOnlyError,
   SyncEngine: () => SyncEngine,
   TamperedError: () => TamperedError,
@@ -44,9 +47,15 @@ __export(index_exports, {
   diff: () => diff,
   enrollBiometric: () => enrollBiometric,
   estimateEntropy: () => estimateEntropy,
+  estimateRecordBytes: () => estimateRecordBytes,
+  evaluateClause: () => evaluateClause,
+  evaluateFieldClause: () => evaluateFieldClause,
+  executePlan: () => executePlan,
   formatDiff: () => formatDiff,
   isBiometricAvailable: () => isBiometricAvailable,
   loadBiometric: () => loadBiometric,
+  parseBytes: () => parseBytes,
+  readPath: () => readPath,
   removeBiometric: () => removeBiometric,
   saveBiometric: () => saveBiometric,
   unlockBiometric: () => unlockBiometric,
@@ -639,7 +648,627 @@ function formatDiff(changes) {
   }).join("\n");
 }
 
+// src/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function evaluateFieldClause(record, clause) {
+  const actual = readPath(record, clause.field);
+  const { op, value } = clause;
+  switch (op) {
+    case "==":
+      return actual === value;
+    case "!=":
+      return actual !== value;
+    case "<":
+      return isComparable(actual, value) && actual < value;
+    case "<=":
+      return isComparable(actual, value) && actual <= value;
+    case ">":
+      return isComparable(actual, value) && actual > value;
+    case ">=":
+      return isComparable(actual, value) && actual >= value;
+    case "in":
+      return Array.isArray(value) && value.includes(actual);
+    case "contains":
+      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
+      if (Array.isArray(actual)) return actual.includes(value);
+      return false;
+    case "startsWith":
+      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) return false;
+      const [lo, hi] = value;
+      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
+      return actual >= lo && actual <= hi;
+    }
+    default: {
+      const _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+function isComparable(a, b) {
+  if (typeof a === "number" && typeof b === "number") return true;
+  if (typeof a === "string" && typeof b === "string") return true;
+  if (a instanceof Date && b instanceof Date) return true;
+  return false;
+}
+function evaluateClause(record, clause) {
+  switch (clause.type) {
+    case "field":
+      return evaluateFieldClause(record, clause);
+    case "filter":
+      return clause.fn(record);
+    case "group":
+      if (clause.op === "and") {
+        for (const child of clause.clauses) {
+          if (!evaluateClause(record, child)) return false;
+        }
+        return true;
+      } else {
+        for (const child of clause.clauses) {
+          if (evaluateClause(record, child)) return true;
+        }
+        return false;
+      }
+  }
+}
+
+// src/query/builder.ts
+var EMPTY_PLAN = {
+  clauses: [],
+  orderBy: [],
+  limit: void 0,
+  offset: 0
+};
+var Query = class _Query {
+  source;
+  plan;
+  constructor(source, plan = EMPTY_PLAN) {
+    this.source = source;
+    this.plan = plan;
+  }
+  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  where(field, op, value) {
+    const clause = { type: "field", field, op, value };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, clause]
+    });
+  }
+  /**
+   * Logical OR group. Pass a callback that builds a sub-query.
+   * Each clause inside the callback is OR-combined; the group itself
+   * joins the parent plan with AND.
+   */
+  or(builder) {
+    const sub = builder(new _Query(this.source));
+    const group = {
+      type: "group",
+      op: "or",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, group]
+    });
+  }
+  /**
+   * Logical AND group. Same shape as `or()` but every clause inside the group
+   * must match. Useful for explicit grouping inside a larger OR.
+   */
+  and(builder) {
+    const sub = builder(new _Query(this.source));
+    const group = {
+      type: "group",
+      op: "and",
+      clauses: sub.plan.clauses
+    };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, group]
+    });
+  }
+  /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+  filter(fn) {
+    const clause = {
+      type: "filter",
+      fn
+    };
+    return new _Query(this.source, {
+      ...this.plan,
+      clauses: [...this.plan.clauses, clause]
+    });
+  }
+  /** Sort by a field. Subsequent calls are tie-breakers. */
+  orderBy(field, direction = "asc") {
+    return new _Query(this.source, {
+      ...this.plan,
+      orderBy: [...this.plan.orderBy, { field, direction }]
+    });
+  }
+  /** Cap the result size. */
+  limit(n) {
+    return new _Query(this.source, { ...this.plan, limit: n });
+  }
+  /** Skip the first N matching records (after ordering). */
+  offset(n) {
+    return new _Query(this.source, { ...this.plan, offset: n });
+  }
+  /** Execute the plan and return the matching records. */
+  toArray() {
+    return executePlanWithSource(this.source, this.plan);
+  }
+  /** Return the first matching record, or null. */
+  first() {
+    const result = executePlanWithSource(this.source, { ...this.plan, limit: 1 });
+    return result[0] ?? null;
+  }
+  /** Return the number of matching records (after where/filter, before limit). */
+  count() {
+    const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
+    if (remainingClauses.length === 0) return candidates.length;
+    return filterRecords(candidates, remainingClauses).length;
+  }
+  /**
+   * Re-run the query whenever the source notifies of changes.
+   * Returns an unsubscribe function. The callback receives the latest result.
+   * Throws if the source does not support subscriptions.
+   */
+  subscribe(cb) {
+    if (!this.source.subscribe) {
+      throw new Error("Query source does not support subscriptions. Pass a source with a subscribe() method.");
+    }
+    cb(this.toArray());
+    return this.source.subscribe(() => cb(this.toArray()));
+  }
+  /**
+   * Return the plan as a JSON-friendly object. FilterClause entries are
+   * stripped (their `fn` cannot be serialized) and replaced with
+   * { type: 'filter', fn: '[function]' } so devtools can still see them.
+   */
+  toPlan() {
+    return serializePlan(this.plan);
+  }
+};
+function executePlanWithSource(source, plan) {
+  const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
+  let result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function candidateRecords(source, clauses) {
+  const indexes = source.getIndexes?.();
+  if (!indexes || !source.lookupById || clauses.length === 0) {
+    return { candidates: source.snapshot(), remainingClauses: clauses };
+  }
+  const lookupById = (id) => source.lookupById?.(id);
+  for (let i = 0; i < clauses.length; i++) {
+    const clause = clauses[i];
+    if (clause.type !== "field") continue;
+    if (!indexes.has(clause.field)) continue;
+    let ids = null;
+    if (clause.op === "==") {
+      ids = indexes.lookupEqual(clause.field, clause.value);
+    } else if (clause.op === "in" && Array.isArray(clause.value)) {
+      ids = indexes.lookupIn(clause.field, clause.value);
+    }
+    if (ids !== null) {
+      const remaining = [];
+      for (let j = 0; j < clauses.length; j++) {
+        if (j !== i) remaining.push(clauses[j]);
+      }
+      return {
+        candidates: materializeIds(ids, lookupById),
+        remainingClauses: remaining
+      };
+    }
+  }
+  return { candidates: source.snapshot(), remainingClauses: clauses };
+}
+function materializeIds(ids, lookupById) {
+  const out = [];
+  for (const id of ids) {
+    const record = lookupById(id);
+    if (record !== void 0) out.push(record);
+  }
+  return out;
+}
+function executePlan(records, plan) {
+  let result = filterRecords(records, plan.clauses);
+  if (plan.orderBy.length > 0) {
+    result = sortRecords(result, plan.orderBy);
+  }
+  if (plan.offset > 0) {
+    result = result.slice(plan.offset);
+  }
+  if (plan.limit !== void 0) {
+    result = result.slice(0, plan.limit);
+  }
+  return result;
+}
+function filterRecords(records, clauses) {
+  if (clauses.length === 0) return [...records];
+  const out = [];
+  for (const r of records) {
+    let matches = true;
+    for (const clause of clauses) {
+      if (!evaluateClause(r, clause)) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) out.push(r);
+  }
+  return out;
+}
+function sortRecords(records, orderBy) {
+  return [...records].sort((a, b) => {
+    for (const { field, direction } of orderBy) {
+      const av = readField(a, field);
+      const bv = readField(b, field);
+      const cmp = compareValues(av, bv);
+      if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
+    }
+    return 0;
+  });
+}
+function readField(record, field) {
+  if (record === null || record === void 0) return void 0;
+  if (!field.includes(".")) {
+    return record[field];
+  }
+  const segments = field.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function compareValues(a, b) {
+  if (a === void 0 || a === null) return b === void 0 || b === null ? 0 : 1;
+  if (b === void 0 || b === null) return -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  return 0;
+}
+function serializePlan(plan) {
+  return {
+    clauses: plan.clauses.map(serializeClause),
+    orderBy: plan.orderBy,
+    limit: plan.limit,
+    offset: plan.offset
+  };
+}
+function serializeClause(clause) {
+  if (clause.type === "filter") {
+    return { type: "filter", fn: "[function]" };
+  }
+  if (clause.type === "group") {
+    return {
+      type: "group",
+      op: clause.op,
+      clauses: clause.clauses.map(serializeClause)
+    };
+  }
+  return clause;
+}
+
+// src/query/indexes.ts
+var CollectionIndexes = class {
+  indexes = /* @__PURE__ */ new Map();
+  /**
+   * Declare an index. Subsequent record additions are tracked under it.
+   * Calling this twice for the same field is a no-op (idempotent).
+   */
+  declare(field) {
+    if (this.indexes.has(field)) return;
+    this.indexes.set(field, { field, buckets: /* @__PURE__ */ new Map() });
+  }
+  /** True if the given field has a declared index. */
+  has(field) {
+    return this.indexes.has(field);
+  }
+  /** All declared field names, in declaration order. */
+  fields() {
+    return [...this.indexes.keys()];
+  }
+  /**
+   * Build all declared indexes from a snapshot of records.
+   * Called once per hydration. O(N × indexes.size).
+   */
+  build(records) {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+      for (const { id, record } of records) {
+        addToIndex(idx, id, record);
+      }
+    }
+  }
+  /**
+   * Insert or update a single record across all indexes.
+   * Called by `Collection.put()` after the encrypted write succeeds.
+   *
+   * If `previousRecord` is provided, the record is removed from any old
+   * buckets first — this is the update path. Pass `null` for fresh adds.
+   */
+  upsert(id, newRecord, previousRecord) {
+    if (this.indexes.size === 0) return;
+    if (previousRecord !== null) {
+      this.remove(id, previousRecord);
+    }
+    for (const idx of this.indexes.values()) {
+      addToIndex(idx, id, newRecord);
+    }
+  }
+  /**
+   * Remove a record from all indexes. Called by `Collection.delete()`
+   * (and as the first half of `upsert` for the update path).
+   */
+  remove(id, record) {
+    if (this.indexes.size === 0) return;
+    for (const idx of this.indexes.values()) {
+      removeFromIndex(idx, id, record);
+    }
+  }
+  /** Drop all index data. Called when the collection is invalidated. */
+  clear() {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+    }
+  }
+  /**
+   * Equality lookup: return the set of record ids whose `field` matches
+   * the given value. Returns `null` if no index covers the field — the
+   * caller should fall back to a linear scan.
+   *
+   * The returned Set is a reference to the index's internal storage —
+   * callers must NOT mutate it.
+   */
+  lookupEqual(field, value) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const key = stringifyKey(value);
+    return idx.buckets.get(key) ?? EMPTY_SET;
+  }
+  /**
+   * Set lookup: return the union of record ids whose `field` matches any
+   * of the given values. Returns `null` if no index covers the field.
+   */
+  lookupIn(field, values) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const out = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const key = stringifyKey(value);
+      const bucket = idx.buckets.get(key);
+      if (bucket) {
+        for (const id of bucket) out.add(id);
+      }
+    }
+    return out;
+  }
+};
+var EMPTY_SET = /* @__PURE__ */ new Set();
+function stringifyKey(value) {
+  if (value === null || value === void 0) return "\0NULL\0";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return "\0OBJECT\0";
+}
+function addToIndex(idx, id, record) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = stringifyKey(value);
+  let bucket = idx.buckets.get(key);
+  if (!bucket) {
+    bucket = /* @__PURE__ */ new Set();
+    idx.buckets.set(key, bucket);
+  }
+  bucket.add(id);
+}
+function removeFromIndex(idx, id, record) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = stringifyKey(value);
+  const bucket = idx.buckets.get(key);
+  if (!bucket) return;
+  bucket.delete(id);
+  if (bucket.size === 0) idx.buckets.delete(key);
+}
+
+// src/cache/lru.ts
+var Lru = class {
+  entries = /* @__PURE__ */ new Map();
+  maxRecords;
+  maxBytes;
+  currentBytes = 0;
+  hits = 0;
+  misses = 0;
+  evictions = 0;
+  constructor(options) {
+    if (options.maxRecords === void 0 && options.maxBytes === void 0) {
+      throw new Error("Lru: must specify maxRecords, maxBytes, or both");
+    }
+    this.maxRecords = options.maxRecords;
+    this.maxBytes = options.maxBytes;
+  }
+  /**
+   * Look up a key. Hits promote the entry to most-recently-used; misses
+   * return undefined. Both update the running stats counters.
+   */
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    this.hits++;
+    return entry.value;
+  }
+  /**
+   * Insert or update a key. If the key already exists, its size is
+   * accounted for and the entry is promoted to MRU. After insertion,
+   * eviction runs to maintain both budgets.
+   */
+  set(key, value, size) {
+    const existing = this.entries.get(key);
+    if (existing) {
+      this.currentBytes -= existing.size;
+      this.entries.delete(key);
+    }
+    this.entries.set(key, { value, size });
+    this.currentBytes += size;
+    this.evictUntilUnderBudget();
+  }
+  /**
+   * Remove a key without affecting hit/miss stats. Used by `Collection.delete()`.
+   * Returns true if the key was present.
+   */
+  remove(key) {
+    const existing = this.entries.get(key);
+    if (!existing) return false;
+    this.currentBytes -= existing.size;
+    this.entries.delete(key);
+    return true;
+  }
+  /** True if the cache currently holds an entry for the given key. */
+  has(key) {
+    return this.entries.has(key);
+  }
+  /**
+   * Drop every entry. Stats counters survive — call `resetStats()` if you
+   * want a clean slate. Used by `Collection.invalidate()` on key rotation.
+   */
+  clear() {
+    this.entries.clear();
+    this.currentBytes = 0;
+  }
+  /** Reset hit/miss/eviction counters to zero. Does NOT touch entries. */
+  resetStats() {
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
+  }
+  /** Snapshot of current cache statistics. Cheap — no copying. */
+  stats() {
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      evictions: this.evictions,
+      size: this.entries.size,
+      bytes: this.currentBytes
+    };
+  }
+  /**
+   * Iterate over all currently-cached values. Order is least-recently-used
+   * first. Used by tests and devtools — production callers should use
+   * `Collection.scan()` instead.
+   */
+  *values() {
+    for (const entry of this.entries.values()) yield entry.value;
+  }
+  /**
+   * Walk the cache from the LRU end and drop entries until both budgets
+   * are satisfied. Called after every `set()`. Single pass — entries are
+   * never re-promoted during eviction.
+   */
+  evictUntilUnderBudget() {
+    while (this.overBudget()) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) return;
+      const key = oldest.value;
+      const entry = this.entries.get(key);
+      if (entry) this.currentBytes -= entry.size;
+      this.entries.delete(key);
+      this.evictions++;
+    }
+  }
+  overBudget() {
+    if (this.maxRecords !== void 0 && this.entries.size > this.maxRecords) return true;
+    if (this.maxBytes !== void 0 && this.currentBytes > this.maxBytes) return true;
+    return false;
+  }
+};
+
+// src/cache/policy.ts
+var UNITS = {
+  "": 1,
+  "B": 1,
+  "KB": 1024,
+  "MB": 1024 * 1024,
+  "GB": 1024 * 1024 * 1024
+  // 'TB' deliberately not supported — if you need it, you're not using NOYDB.
+};
+function parseBytes(input) {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input) || input <= 0) {
+      throw new Error(`parseBytes: numeric input must be a positive finite number, got ${String(input)}`);
+    }
+    return Math.floor(input);
+  }
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new Error("parseBytes: empty string is not a valid byte budget");
+  }
+  const match = /^([0-9]+(?:\.[0-9]+)?)\s*([A-Za-z]*)$/.exec(trimmed);
+  if (!match) {
+    throw new Error(`parseBytes: invalid byte budget "${input}". Expected format: "1024", "50KB", "50MB", "1GB"`);
+  }
+  const value = parseFloat(match[1]);
+  const unit = (match[2] ?? "").toUpperCase();
+  if (!(unit in UNITS)) {
+    throw new Error(`parseBytes: unknown unit "${match[2]}" in "${input}". Supported: B, KB, MB, GB`);
+  }
+  const bytes = Math.floor(value * UNITS[unit]);
+  if (bytes <= 0) {
+    throw new Error(`parseBytes: byte budget must be > 0, got ${bytes} from "${input}"`);
+  }
+  return bytes;
+}
+function estimateRecordBytes(record) {
+  try {
+    return JSON.stringify(record).length;
+  } catch {
+    return 0;
+  }
+}
+
 // src/collection.ts
+var fallbackWarned = /* @__PURE__ */ new Set();
+function warnOnceFallback(adapterName) {
+  if (fallbackWarned.has(adapterName)) return;
+  fallbackWarned.add(adapterName);
+  if (typeof process !== "undefined" && process.env["NODE_ENV"] === "test") return;
+  console.warn(
+    `[noy-db] Adapter "${adapterName}" does not implement listPage(); Collection.scan()/listPage() are using a synthetic fallback (slower). Add a listPage method to opt into the streaming fast path.`
+  );
+}
 var Collection = class {
   adapter;
   compartment;
@@ -650,9 +1279,41 @@ var Collection = class {
   getDEK;
   onDirty;
   historyConfig;
-  // In-memory cache of decrypted records
+  // In-memory cache of decrypted records (eager mode only). Lazy mode
+  // uses `lru` instead. Both fields exist so a single Collection instance
+  // doesn't need a runtime branch on every cache access.
   cache = /* @__PURE__ */ new Map();
   hydrated = false;
+  /**
+   * Lazy mode flag. `true` when constructed with `prefetch: false`.
+   * In lazy mode the cache is bounded by an LRU and `list()`/`query()`
+   * throw — callers must use `scan()` or per-id `get()` instead.
+   */
+  lazy;
+  /**
+   * LRU cache for lazy mode. Only allocated when `prefetch: false` is set.
+   * Stores `{ record, version }` entries the same shape as `this.cache`.
+   * Tree-shaking note: importing Collection without setting `prefetch:false`
+   * still pulls in the Lru class today; future bundle-size work could
+   * lazy-import the cache module.
+   */
+  lru;
+  /**
+   * In-memory secondary indexes for the query DSL.
+   *
+   * Built during `ensureHydrated()` and maintained on every put/delete.
+   * The query executor consults these for `==` and `in` operators on
+   * indexed fields, falling back to a linear scan for unindexed fields
+   * or unsupported operators.
+   *
+   * v0.3 ships in-memory only — persistence as encrypted blobs is a
+   * follow-up. See `query/indexes.ts` for the design rationale.
+   *
+   * Indexes are INCOMPATIBLE with lazy mode in v0.3 — the constructor
+   * rejects the combination because evicted records would silently
+   * disappear from the index without notification.
+   */
+  indexes = new CollectionIndexes();
   constructor(opts) {
     this.adapter = opts.adapter;
     this.compartment = opts.compartment;
@@ -663,9 +1324,43 @@ var Collection = class {
     this.getDEK = opts.getDEK;
     this.onDirty = opts.onDirty;
     this.historyConfig = opts.historyConfig ?? { enabled: true };
+    this.lazy = opts.prefetch === false;
+    if (this.lazy) {
+      if (opts.indexes && opts.indexes.length > 0) {
+        throw new Error(
+          `Collection "${this.name}": secondary indexes are not supported in lazy mode (prefetch: false). Either remove the indexes option or use prefetch: true. Index + lazy support is tracked as a v0.4 follow-up.`
+        );
+      }
+      if (!opts.cache || opts.cache.maxRecords === void 0 && opts.cache.maxBytes === void 0) {
+        throw new Error(
+          `Collection "${this.name}": lazy mode (prefetch: false) requires a cache option with maxRecords and/or maxBytes. An unbounded lazy cache defeats the purpose.`
+        );
+      }
+      const lruOptions = {};
+      if (opts.cache.maxRecords !== void 0) lruOptions.maxRecords = opts.cache.maxRecords;
+      if (opts.cache.maxBytes !== void 0) lruOptions.maxBytes = parseBytes(opts.cache.maxBytes);
+      this.lru = new Lru(lruOptions);
+      this.hydrated = true;
+    } else {
+      this.lru = null;
+      if (opts.indexes) {
+        for (const def of opts.indexes) {
+          this.indexes.declare(def);
+        }
+      }
+    }
   }
   /** Get a single record by ID. Returns null if not found. */
   async get(id) {
+    if (this.lazy && this.lru) {
+      const cached = this.lru.get(id);
+      if (cached) return cached.record;
+      const envelope = await this.adapter.get(this.compartment, this.name, id);
+      if (!envelope) return null;
+      const record = await this.decryptRecord(envelope);
+      this.lru.set(id, { record, version: envelope._v }, estimateRecordBytes(record));
+      return record;
+    }
     await this.ensureHydrated();
     const entry = this.cache.get(id);
     return entry ? entry.record : null;
@@ -675,8 +1370,20 @@ var Collection = class {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
-    await this.ensureHydrated();
-    const existing = this.cache.get(id);
+    let existing;
+    if (this.lazy && this.lru) {
+      existing = this.lru.get(id);
+      if (!existing) {
+        const previousEnvelope = await this.adapter.get(this.compartment, this.name, id);
+        if (previousEnvelope) {
+          const previousRecord = await this.decryptRecord(previousEnvelope);
+          existing = { record: previousRecord, version: previousEnvelope._v };
+        }
+      }
+    } else {
+      await this.ensureHydrated();
+      existing = this.cache.get(id);
+    }
     const version = existing ? existing.version + 1 : 1;
     if (existing && this.historyConfig.enabled !== false) {
       const historyEnvelope = await this.encryptRecord(existing.record, existing.version);
@@ -695,7 +1402,12 @@ var Collection = class {
     }
     const envelope = await this.encryptRecord(record, version);
     await this.adapter.put(this.compartment, this.name, id, envelope);
-    this.cache.set(id, { record, version });
+    if (this.lazy && this.lru) {
+      this.lru.set(id, { record, version }, estimateRecordBytes(record));
+    } else {
+      this.cache.set(id, { record, version });
+      this.indexes.upsert(id, record, existing ? existing.record : null);
+    }
     await this.onDirty?.(this.name, id, "put", version);
     this.emitter.emit("change", {
       compartment: this.compartment,
@@ -709,13 +1421,32 @@ var Collection = class {
     if (!hasWritePermission(this.keyring, this.name)) {
       throw new ReadOnlyError();
     }
-    const existing = this.cache.get(id);
+    let existing;
+    if (this.lazy && this.lru) {
+      existing = this.lru.get(id);
+      if (!existing && this.historyConfig.enabled !== false) {
+        const previousEnvelope = await this.adapter.get(this.compartment, this.name, id);
+        if (previousEnvelope) {
+          const previousRecord = await this.decryptRecord(previousEnvelope);
+          existing = { record: previousRecord, version: previousEnvelope._v };
+        }
+      }
+    } else {
+      existing = this.cache.get(id);
+    }
     if (existing && this.historyConfig.enabled !== false) {
       const historyEnvelope = await this.encryptRecord(existing.record, existing.version);
       await saveHistory(this.adapter, this.compartment, this.name, id, historyEnvelope);
     }
     await this.adapter.delete(this.compartment, this.name, id);
-    this.cache.delete(id);
+    if (this.lazy && this.lru) {
+      this.lru.remove(id);
+    } else {
+      this.cache.delete(id);
+      if (existing) {
+        this.indexes.remove(id, existing.record);
+      }
+    }
     await this.onDirty?.(this.name, id, "delete", existing?.version ?? 0);
     this.emitter.emit("change", {
       compartment: this.compartment,
@@ -724,14 +1455,70 @@ var Collection = class {
       action: "delete"
     });
   }
-  /** List all records in the collection. */
+  /**
+   * List all records in the collection.
+   *
+   * Throws in lazy mode — bulk listing defeats the purpose of lazy
+   * hydration. Use `scan()` to iterate over the full collection
+   * page-by-page without holding more than `pageSize` records in memory.
+   */
   async list() {
+    if (this.lazy) {
+      throw new Error(
+        `Collection "${this.name}": list() is not available in lazy mode (prefetch: false). Use collection.scan({ pageSize }) to iterate over the full collection.`
+      );
+    }
     await this.ensureHydrated();
     return [...this.cache.values()].map((e) => e.record);
   }
-  /** Filter records by a predicate. */
   query(predicate) {
-    return [...this.cache.values()].map((e) => e.record).filter(predicate);
+    if (this.lazy) {
+      throw new Error(
+        `Collection "${this.name}": query() is not available in lazy mode (prefetch: false). Use collection.scan({ pageSize }) and filter the streamed records with a regular for-await loop. Streaming queries land in v0.4.`
+      );
+    }
+    if (predicate !== void 0) {
+      return [...this.cache.values()].map((e) => e.record).filter(predicate);
+    }
+    const source = {
+      snapshot: () => [...this.cache.values()].map((e) => e.record),
+      subscribe: (cb) => {
+        const handler = (event) => {
+          if (event.compartment === this.compartment && event.collection === this.name) {
+            cb();
+          }
+        };
+        this.emitter.on("change", handler);
+        return () => this.emitter.off("change", handler);
+      },
+      // Index-aware fast path for `==` and `in` operators on indexed
+      // fields. The Query builder consults these when present and falls
+      // back to a linear scan otherwise.
+      getIndexes: () => this.getIndexes(),
+      lookupById: (id) => this.cache.get(id)?.record
+    };
+    return new Query(source);
+  }
+  /**
+   * Cache statistics — useful for devtools, monitoring, and verifying
+   * that LRU eviction is happening as expected in lazy mode.
+   *
+   * In eager mode, returns size only (no hits/misses are tracked because
+   * every read is a cache hit by construction). In lazy mode, returns
+   * the full LRU stats: `{ hits, misses, evictions, size, bytes }`.
+   */
+  cacheStats() {
+    if (this.lazy && this.lru) {
+      return { ...this.lru.stats(), lazy: true };
+    }
+    return {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      size: this.cache.size,
+      bytes: 0,
+      lazy: false
+    };
   }
   // ─── History Methods ────────────────────────────────────────────
   /** Get version history for a record, newest first. */
@@ -822,11 +1609,105 @@ var Collection = class {
     return clearHistory(this.adapter, this.compartment, this.name, id);
   }
   // ─── Core Methods ─────────────────────────────────────────────
-  /** Count records in the collection. */
+  /**
+   * Count records in the collection.
+   *
+   * In eager mode this returns the in-memory cache size (instant). In
+   * lazy mode it asks the adapter via `list()` to enumerate ids — slower
+   * but still correct, and avoids loading any record bodies into memory.
+   */
   async count() {
+    if (this.lazy) {
+      const ids = await this.adapter.list(this.compartment, this.name);
+      return ids.length;
+    }
     await this.ensureHydrated();
     return this.cache.size;
   }
+  // ─── Pagination & Streaming ───────────────────────────────────
+  /**
+   * Fetch a single page of records via the adapter's optional `listPage`
+   * extension. Returns the decrypted records for this page plus an opaque
+   * cursor for the next page.
+   *
+   * Pass `cursor: undefined` (or omit it) to start from the beginning.
+   * The final page returns `nextCursor: null`.
+   *
+   * If the adapter does NOT implement `listPage`, this falls back to a
+   * synthetic implementation: it loads all ids via `list()`, sorts them,
+   * and slices a window. The first call emits a one-time console.warn so
+   * developers can spot adapters that should opt into the fast path.
+   */
+  async listPage(opts = {}) {
+    const limit = opts.limit ?? 100;
+    if (this.adapter.listPage) {
+      const result = await this.adapter.listPage(this.compartment, this.name, opts.cursor, limit);
+      const decrypted = [];
+      for (const { record, version, id } of await this.decryptPage(result.items)) {
+        if (!this.lazy && !this.cache.has(id)) {
+          this.cache.set(id, { record, version });
+        }
+        decrypted.push(record);
+      }
+      return { items: decrypted, nextCursor: result.nextCursor };
+    }
+    warnOnceFallback(this.adapter.name ?? "unknown");
+    const ids = (await this.adapter.list(this.compartment, this.name)).slice().sort();
+    const start = opts.cursor ? parseInt(opts.cursor, 10) : 0;
+    const end = Math.min(start + limit, ids.length);
+    const items = [];
+    for (let i = start; i < end; i++) {
+      const id = ids[i];
+      const envelope = await this.adapter.get(this.compartment, this.name, id);
+      if (envelope) {
+        const record = await this.decryptRecord(envelope);
+        items.push(record);
+        if (!this.lazy && !this.cache.has(id)) {
+          this.cache.set(id, { record, version: envelope._v });
+        }
+      }
+    }
+    return {
+      items,
+      nextCursor: end < ids.length ? String(end) : null
+    };
+  }
+  /**
+   * Stream every record in the collection page-by-page, yielding decrypted
+   * records as an `AsyncIterable<T>`. The whole point: process collections
+   * larger than RAM without ever holding more than `pageSize` records
+   * decrypted at once.
+   *
+   * @example
+   * ```ts
+   * for await (const record of invoices.scan({ pageSize: 500 })) {
+   *   await processOne(record)
+   * }
+   * ```
+   *
+   * Uses `adapter.listPage` when available; otherwise falls back to the
+   * synthetic pagination path with the same one-time warning.
+   */
+  async *scan(opts = {}) {
+    const pageSize = opts.pageSize ?? 100;
+    let page = await this.listPage({ limit: pageSize });
+    while (true) {
+      for (const item of page.items) {
+        yield item;
+      }
+      if (page.nextCursor === null) return;
+      page = await this.listPage({ cursor: page.nextCursor, limit: pageSize });
+    }
+  }
+  /** Decrypt a page of envelopes returned by `adapter.listPage`. */
+  async decryptPage(items) {
+    const out = [];
+    for (const { id, envelope } of items) {
+      const record = await this.decryptRecord(envelope);
+      out.push({ id, record, version: envelope._v });
+    }
+    return out;
+  }
   // ─── Internal ──────────────────────────────────────────────────
   /** Load all records from adapter into memory cache. */
   async ensureHydrated() {
@@ -840,6 +1721,7 @@ var Collection = class {
       }
     }
     this.hydrated = true;
+    this.rebuildIndexes();
   }
   /** Hydrate from a pre-loaded snapshot (used by Compartment). */
   async hydrateFromSnapshot(records) {
@@ -848,6 +1730,34 @@ var Collection = class {
       this.cache.set(id, { record, version: envelope._v });
     }
     this.hydrated = true;
+    this.rebuildIndexes();
+  }
+  /**
+   * Rebuild secondary indexes from the current in-memory cache.
+   *
+   * Called after any bulk hydration. Incremental put/delete updates
+   * are handled by `indexes.upsert()` / `indexes.remove()` directly,
+   * so this only fires for full reloads.
+   *
+   * Synchronous and O(N × indexes.size); for the v0.3 target scale of
+   * 1K–50K records this completes in single-digit milliseconds.
+   */
+  rebuildIndexes() {
+    if (this.indexes.fields().length === 0) return;
+    const snapshot = [];
+    for (const [id, entry] of this.cache) {
+      snapshot.push({ id, record: entry.record });
+    }
+    this.indexes.build(snapshot);
+  }
+  /**
+   * Get the in-memory index store. Used by `Query` to short-circuit
+   * `==` and `in` lookups when an index covers the where clause.
+   *
+   * Returns `null` if no indexes are declared on this collection.
+   */
+  getIndexes() {
+    return this.indexes.fields().length > 0 ? this.indexes : null;
   }
   /** Get all records as encrypted envelopes (for dump). */
   async dumpEnvelopes() {
@@ -919,11 +1829,25 @@ var Compartment = class {
       return getDEKFn(collectionName);
     };
   }
-  /** Open a typed collection within this compartment. */
-  collection(collectionName) {
+  /**
+   * Open a typed collection within this compartment.
+   *
+   * - `options.indexes` declares secondary indexes for the query DSL.
+   *   Indexes are computed in memory after decryption; adapters never
+   *   see plaintext index data.
+   * - `options.prefetch` (default `true`) controls hydration. Eager mode
+   *   loads everything on first access; lazy mode (`prefetch: false`)
+   *   loads records on demand and bounds memory via the LRU cache.
+   * - `options.cache` configures the LRU bounds. Required in lazy mode.
+   *   Accepts `{ maxRecords, maxBytes: '50MB' | 1024 }`.
+   *
+   * Lazy mode + indexes is rejected at construction time — see the
+   * Collection constructor for the rationale.
+   */
+  collection(collectionName, options) {
     let coll = this.collectionCache.get(collectionName);
     if (!coll) {
-      coll = new Collection({
+      const collOpts = {
         adapter: this.adapter,
         compartment: this.name,
         name: collectionName,
@@ -933,7 +1857,11 @@ var Compartment = class {
         getDEK: this.getDEK,
         onDirty: this.onDirty,
         historyConfig: this.historyConfig
-      });
+      };
+      if (options?.indexes !== void 0) collOpts.indexes = options.indexes;
+      if (options?.prefetch !== void 0) collOpts.prefetch = options.prefetch;
+      if (options?.cache !== void 0) collOpts.cache = options.cache;
+      coll = new Collection(collOpts);
       this.collectionCache.set(collectionName, coll);
     }
     return coll;
@@ -1634,10 +2562,12 @@ function estimateEntropy(passphrase) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Collection,
+  CollectionIndexes,
   Compartment,
   ConflictError,
   DecryptionError,
   InvalidKeyError,
+  Lru,
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION,
   NOYDB_KEYRING_VERSION,
@@ -1648,6 +2578,7 @@ function estimateEntropy(passphrase) {
   Noydb,
   NoydbError,
   PermissionDeniedError,
+  Query,
   ReadOnlyError,
   SyncEngine,
   TamperedError,
@@ -1657,9 +2588,15 @@ function estimateEntropy(passphrase) {
   diff,
   enrollBiometric,
   estimateEntropy,
+  estimateRecordBytes,
+  evaluateClause,
+  evaluateFieldClause,
+  executePlan,
   formatDiff,
   isBiometricAvailable,
   loadBiometric,
+  parseBytes,
+  readPath,
   removeBiometric,
   saveBiometric,
   unlockBiometric,