rumongo 0.1.0

package/README.md

@@ -0,0 +1,255 @@
+# rumongo
+
+**Rust + Mongo.** A Rust-native MongoDB **read** driver for Node.js (napi-rs).
+Faster reads than the official Node driver and Mongoose by doing BSON parsing in
+Rust — pipelined fetch, off-thread parallel parse, and optional lazy zero-copy
+field access.
+
+> Read path only. Writes / hooks / virtuals / populate / validation are **not**
+> covered — keep the official driver or Mongoose for those. See
+> [MIGRATION.md](MIGRATION.md).
+
+## Performance
+
+- **1.6–3.7× faster reads** than the official Node driver (by projection width).
+- **~2× vs Mongoose `.lean()`, ~5× vs hydrated Mongoose.**
+- **~10× lower event-loop jitter** on a single query; **near-zero** with lazy or
+  worker-thread offload.
+- **7.3× vs the raw driver** when reading a few fields of a wide doc (lazy).
+
+### Final benchmark results
+
+Consolidated preset suite (`bench/suite.js`), 30k docs over a 45-field document,
+warmup + 6 iters, mean ± sd. Local MongoDB 8.0, Node v20.4, 12 cores.
+[BENCHMARKS.md](BENCHMARKS.md) keeps the **full progressive log** (every phase);
+the tables below are the **final snapshot**.
+
+**A) Driver `find` — official Node driver vs rumongo (eager)**
+
+| preset | fields | official (ms) | rumongo (ms) | speedup |
+|---|---|---|---|---|
+| few | 4 | 649 ± 95 | 178 ± 17 | **3.65×** |
+| small | 9 | 792 ± 62 | 304 ± 16 | 2.61× |
+| medium | 15 | 687 ± 49 | 418 ± 54 | 1.64× |
+| large | 35 | 1532 ± 132 | 841 ± 61 | 1.82× |
+| full | 45 | 2032 ± 135 | 1031 ± 59 | 1.97× |
+
+**B) ODM — Mongoose `.lean()` vs rumongo Model**
+
+| preset | fields | mongoose (ms) | Model (ms) | speedup |
+|---|---|---|---|---|
+| few | 4 | 477 ± 53 | 177 ± 18 | 2.69× |
+| small | 9 | 559 ± 35 | 284 ± 31 | 1.97× |
+| medium | 15 | 680 ± 68 | 405 ± 35 | 1.68× |
+| large | 35 | 1455 ± 24 | 850 ± 65 | 1.71× |
+| full | 45 | 2041 ± 167 | 1031 ± 98 | 1.98× |
+
+**C) Event-loop jitter** (full preset, single query): official `149.2ms` ·
+rumongo `13.8ms` (~10× lower).
+
+**D) Lazy / wide-doc, few-field read** (20k docs × 33 fields, read 2 fields, 10
+concurrent): rumongo lazy **7.3× vs the official driver**, 2.2× vs rumongo eager.
+
+> ⚠️ All numbers are **localhost** (≈0 network latency) — a lower bound for
+> pipeline/concurrency wins, upper bound for CPU-bound wins. The headline 15–20×
+> shows up only under lazy/narrow-read or worker-offload patterns, not eager
+> full-document reads.
+
+## How it works (in plain terms)
+
+MongoDB sends every document over the wire as **BSON** — a compact binary blob.
+Before your code can use it, something has to **decode** that binary into objects
+you can read (`doc.name`, `doc.age`, …). The whole speed difference comes down to
+two questions: **who** does the decoding (the single JavaScript thread, or many
+Rust CPU cores) and **how much** it decodes (every field, or only the ones you touch).
+
+### 1. A normal `find` — who decodes the data?
+
+The official driver does all the binary→object work on the **one** thread that
+also runs your entire app. rumongo hands that work to Rust, spread across CPU
+cores, **off** the main thread — so your app stays responsive.
+
+```mermaid
+flowchart TB
+  subgraph OFF["🔵 Official Node driver"]
+    direction TB
+    O1["MongoDB sends BSON (binary)"]
+    O2["JS main thread decodes<br/>every field of every doc"]
+    O3["Builds thousands of JS objects<br/>(heavy garbage collection)"]
+    O4["Your code gets the docs"]
+    O1 --> O2 --> O3 --> O4
+    OX(["⚠️ All on the ONE thread that<br/>runs your app → event loop frozen"])
+    O2 -.-> OX
+  end
+
+  subgraph RU["🟢 rumongo (Rust)"]
+    direction TB
+    R1["MongoDB sends BSON (binary)"]
+    R2["Rust fetches batches in a pipeline<br/>(network + parsing overlap)"]
+    R3["Many CPU cores decode<br/>batches in parallel"]
+    R4["Hand finished result back to JS"]
+    R5["Your code gets the docs"]
+    R1 --> R2 --> R3 --> R4 --> R5
+    RX(["✅ Done in Rust, OFF the JS thread<br/>→ main event loop stays free"])
+    R3 -.-> RX
+  end
+```
+
+### 2. `findLazy` — how much does it decode?
+
+Each document may have 25 fields, but your loop might read only 2. The official
+driver decodes **all** of them up front. rumongo keeps the doc as raw bytes and
+decodes a field **only when you touch it**.
+
+```mermaid
+flowchart LR
+  subgraph OFFL["🔵 Official"]
+    A1["Get a doc"] --> A2["Decode ALL 25 fields<br/>up front"] --> A3["You read 2 →<br/>23 fields of work wasted"]
+  end
+  subgraph RUL["🟢 rumongo findLazy"]
+    B1["Get a doc,<br/>keep it as raw bytes"] --> B2["Decode a field ONLY<br/>when accessed (doc.name)"] --> B3["You read 2 →<br/>decode 2, skip 23"]
+  end
+```
+
+### 3. Concurrent load — why "jitter" stays low
+
+"Jitter" = how long the event loop froze, i.e. how unresponsive your app got to
+*other* users while a query was being decoded. Under many concurrent queries the
+official driver piles every decode onto the single JS thread; rumongo keeps that
+work in Rust, off-thread.
+
+```mermaid
+sequenceDiagram
+  participant App as Your app (event loop)
+  participant JS as Official driver
+  participant Rust as rumongo (Rust threads)
+
+  Note over App,JS: Official — decode runs ON the event loop
+  App->>JS: 10 queries at once
+  JS-->>JS: decode all BSON on the JS thread
+  Note over App: ⛔ loop frozen — other users wait (high jitter)
+  JS-->>App: results
+
+  Note over App,Rust: rumongo — decode runs OFF the event loop
+  App->>Rust: 10 queries at once
+  Rust-->>Rust: decode BSON on Rust CPU cores
+  Note over App: ✅ loop free — app keeps answering (low jitter)
+  Rust-->>App: results
+```
+
+**One line:** the official driver does *all* the binary→object work on the single
+thread that also runs your whole app; rumongo pushes that work into Rust on
+multiple cores, off the main thread, and — in lazy mode — only does the part you
+actually use.
+
+## Install / build
+
+```bash
+npm install          # deps
+npm run build        # compile the Rust addon (release) -> rumongo.<platform>.node
+npm run build:ts     # compile the TypeScript layer -> dist/
+```
+
+Requires a Rust toolchain and a reachable MongoDB. Target: linux-x64 (current).
+
+## Usage
+
+```js
+import { MongoClient } from 'rumongo'
+
+const client = await MongoClient.connect('mongodb://localhost:27017', {
+  maxPoolSize: 20,
+  serverSelectionTimeoutMs: 5000,
+})
+const users = client.collection('app', 'users')
+
+// eager: plain JS objects
+const all = await users.find({ active: true }, { sort: { age: -1 }, limit: 100 })
+
+await client.close() // IMPORTANT: stops background monitors so the process exits
+```
+
+### Three read APIs (pick by shape)
+
+| API | use when |
+|---|---|
+| `collection.find(filter, opts)` | small/medium results; returns plain objects |
+| `collection.findLazy(filter, opts)` | wide docs, few fields read — fields parse on access |
+| `collection.findCursor(filter, opts)` → `nextBatch()` | large/streaming results; bounded memory |
+
+```js
+// lazy: only the fields you touch are parsed
+const docs = await users.findLazy({}, { limit: 1000 })
+for (const d of docs) console.log(d.name) // parses just `name`
+
+// streaming cursor: process a batch at a time (bounded memory)
+const cur = await users.findCursor({}, { batchSize: 1000 })
+let batch
+while ((batch = await cur.nextBatch()) !== null) {
+  for (const d of batch) process(d)
+}
+```
+
+### Mongoose-style Model (projection pushdown)
+
+```js
+import { Model } from 'rumongo'
+const User = Model.define(users, { name: 1, age: 1 }) // schema fields = projection
+await User.find({ age: { $gte: 18 } }, { sort: { age: 1 } })
+await User.findOne({ name: 'Ann' })
+await User.findById('507f1f77bcf86cd799439011') // 24-char hex string
+```
+
+### Filters with BSON types (Extended JSON)
+
+Filters cross the JS↔Rust boundary as JSON, so use Extended JSON for BSON types:
+
+```js
+await users.find({ _id: { $oid: '507f1f77bcf86cd799439011' } })
+```
+
+### Worker pool (opt-in) — keep the main loop free under heavy load
+
+Run aggregation/transform work inside worker threads; only the result returns to
+main, so the event loop stays responsive. Best for "do the work, return a small
+result" (counts, sums, transforms, exports).
+
+```js
+import { WorkerPool } from 'rumongo'
+const pool = await WorkerPool.create({ uri, size: 6 })
+const { acc } = await pool.reduce('app', 'users', { active: true }, {}, (a, d) => a + d.age, 0)
+await pool.close()
+```
+
+### Shadow mode — validate before cutover
+
+Run rumongo alongside the official driver, compare, log divergences, but always
+return the official result.
+
+```js
+import { shadow } from 'rumongo'
+const res = await shadow(
+  () => rumongoColl.find(q),
+  () => officialColl.find(q).toArray(),
+  (diff) => logger.warn('divergence', diff),
+)
+```
+
+## Debugging
+
+Set `RUMONGO_DEBUG=1` to log each query's collection, doc count, and elapsed time
+to stderr.
+
+## Tests
+
+```bash
+node --test __tests__/parity/        # 23 parity tests vs official driver
+node --test __tests__/model/         # 9 Model tests vs Mongoose
+node --test __tests__/lazy/          # lazy field-access tests
+node --test __tests__/integration/   # connectivity, pipeline, leak
+node bench/suite.js                  # benchmark suite
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { MongoClient as NativeClient, FindCursor as NativeCursor } from '../index';
+export { WorkerPool } from '../worker/pool';
+export type { WorkerPoolOptions } from '../worker/pool';
+export { Model, Schema } from './model';
+export type { SchemaDefinition, QueryOptions } from './model';
+export { shadow, deepEqual } from './shadow';
+export type { Divergence } from './shadow';
+export interface ConnectOptions {
+    maxPoolSize?: number;
+    minPoolSize?: number;
+    connectTimeoutMs?: number;
+    serverSelectionTimeoutMs?: number;
+    appName?: string;
+}
+export declare class MongoClient {
+    private readonly native;
+    private constructor();
+    static connect(uri: string, options?: ConnectOptions): Promise<MongoClient>;
+    collection(db: string, name: string): Collection;
+    close(): Promise<void>;
+}
+export declare class Collection {
+    private readonly native;
+    private readonly db;
+    private readonly name;
+    constructor(native: NativeClient, db: string, name: string);
+    /** Eager: fully parsed plain JS objects. */
+    find<T = Record<string, unknown>>(filter?: object, options?: object): Promise<T[]>;
+    /** Lazy: fields parse only when read. Returns Proxy-wrapped documents. */
+    findLazy(filter?: object, options?: object): Promise<Record<string, unknown>[]>;
+    /** Streaming: pull one batch of (Proxy-wrapped) docs at a time. Bounded memory. */
+    findCursor(filter?: object, options?: object): Promise<LazyCursor>;
+}
+/** Wraps the native cursor; each batch's docs are Proxy-wrapped for dot access. */
+export declare class LazyCursor {
+    private readonly native;
+    constructor(native: NativeCursor);
+    /** Next batch of docs, or null when exhausted. */
+    nextBatch(): Promise<Record<string, unknown>[] | null>;
+    /** Async iterator over individual docs across all batches. */
+    [Symbol.asyncIterator](): AsyncGenerator<Record<string, unknown>>;
+}

package/dist/index.js

@@ -0,0 +1,112 @@
+"use strict";
+// Public TypeScript API for rumongo.
+//   - find()      eager: returns plain JS objects (parsed from JSON strings)
+//   - findLazy()  Phase 4: returns Proxy-wrapped RawDoc — fields parse on access
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LazyCursor = exports.Collection = exports.MongoClient = exports.deepEqual = exports.shadow = exports.Schema = exports.Model = exports.WorkerPool = void 0;
+const index_1 = require("../index");
+// Opt-in worker pool (see worker/pool.js). Re-exported as part of the public API.
+var pool_1 = require("../worker/pool");
+Object.defineProperty(exports, "WorkerPool", { enumerable: true, get: function () { return pool_1.WorkerPool; } });
+// Mongoose-style Model + projection pushdown.
+var model_1 = require("./model");
+Object.defineProperty(exports, "Model", { enumerable: true, get: function () { return model_1.Model; } });
+Object.defineProperty(exports, "Schema", { enumerable: true, get: function () { return model_1.Schema; } });
+// Shadow mode (validate rumongo vs official in production).
+var shadow_1 = require("./shadow");
+Object.defineProperty(exports, "shadow", { enumerable: true, get: function () { return shadow_1.shadow; } });
+Object.defineProperty(exports, "deepEqual", { enumerable: true, get: function () { return shadow_1.deepEqual; } });
+// Wrap a RawDoc so `doc.field` parses just that field on demand, while spread
+// (`{...doc}`) and JSON.stringify still see all fields (via ownKeys + descriptors).
+function wrapRawDoc(doc) {
+    return new Proxy(doc, {
+        get(target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            if (prop === 'toObject' || prop === 'toJSON')
+                return () => target.toObject();
+            if (prop === 'toString')
+                return () => JSON.stringify(target.toObject());
+            if (prop === '__isRawDoc')
+                return true;
+            if (prop === 'then')
+                return undefined; // never look thenable
+            return target.getField(prop);
+        },
+        has(target, prop) {
+            return typeof prop === 'string' && target.keys().includes(prop);
+        },
+        ownKeys(target) {
+            return target.keys();
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (typeof prop === 'string' && target.keys().includes(prop)) {
+                return {
+                    enumerable: true,
+                    configurable: true,
+                    value: target.getField(prop),
+                };
+            }
+            return undefined;
+        },
+    });
+}
+class MongoClient {
+    constructor(native) {
+        this.native = native;
+    }
+    static async connect(uri, options) {
+        const opts = options ? JSON.stringify(options) : undefined;
+        return new MongoClient(await index_1.MongoClient.connect(uri, opts));
+    }
+    collection(db, name) {
+        return new Collection(this.native, db, name);
+    }
+    async close() {
+        await this.native.close();
+    }
+}
+exports.MongoClient = MongoClient;
+class Collection {
+    constructor(native, db, name) {
+        this.native = native;
+        this.db = db;
+        this.name = name;
+    }
+    /** Eager: fully parsed plain JS objects. */
+    async find(filter = {}, options = {}) {
+        const rows = await this.native.find(this.db, this.name, JSON.stringify(filter), JSON.stringify(options));
+        return rows.map((r) => JSON.parse(r));
+    }
+    /** Lazy: fields parse only when read. Returns Proxy-wrapped documents. */
+    async findLazy(filter = {}, options = {}) {
+        const docs = await this.native.findLazy(this.db, this.name, JSON.stringify(filter), JSON.stringify(options));
+        return docs.map(wrapRawDoc);
+    }
+    /** Streaming: pull one batch of (Proxy-wrapped) docs at a time. Bounded memory. */
+    async findCursor(filter = {}, options = {}) {
+        const cur = await this.native.findCursor(this.db, this.name, JSON.stringify(filter), JSON.stringify(options));
+        return new LazyCursor(cur);
+    }
+}
+exports.Collection = Collection;
+/** Wraps the native cursor; each batch's docs are Proxy-wrapped for dot access. */
+class LazyCursor {
+    constructor(native) {
+        this.native = native;
+    }
+    /** Next batch of docs, or null when exhausted. */
+    async nextBatch() {
+        const batch = await this.native.nextBatch();
+        return batch === null ? null : batch.map(wrapRawDoc);
+    }
+    /** Async iterator over individual docs across all batches. */
+    async *[Symbol.asyncIterator]() {
+        let batch;
+        while ((batch = await this.nextBatch()) !== null) {
+            for (const d of batch)
+                yield d;
+        }
+    }
+}
+exports.LazyCursor = LazyCursor;

package/dist/model.d.ts

@@ -0,0 +1,27 @@
+import { Collection } from './index';
+export type SchemaDefinition = Record<string, unknown>;
+export declare class Schema {
+    readonly fields: string[];
+    readonly projection: Record<string, 1>;
+    constructor(definition: SchemaDefinition);
+}
+export interface QueryOptions {
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+}
+export declare class Model<T = Record<string, unknown>> {
+    private readonly collection;
+    private readonly schema;
+    private constructor();
+    /** Define a model over a collection from a schema definition. */
+    static define<U = Record<string, unknown>>(collection: Collection, definition: SchemaDefinition): Model<U>;
+    /** The cached projection MongoDB receives (schema fields only). */
+    getProjection(): Record<string, 1>;
+    /** find with the schema projection pushed down. */
+    find(filter?: object, options?: QueryOptions): Promise<T[]>;
+    /** First match, or null. */
+    findOne(filter?: object, options?: QueryOptions): Promise<T | null>;
+    /** Find by _id. Accepts a 24-char hex ObjectId string (Mongoose-style). */
+    findById(id: string, options?: QueryOptions): Promise<T | null>;
+}

package/dist/model.js

@@ -0,0 +1,50 @@
+"use strict";
+// Phase 5 — Mongoose-style Model with projection pushdown.
+//
+// A Model wraps a Collection + a schema (field list). Every query automatically
+// applies a projection of the schema fields, so MongoDB only sends the fields
+// you defined — less wire data, less to parse. The projection is built once and
+// cached.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Model = exports.Schema = void 0;
+class Schema {
+    constructor(definition) {
+        this.fields = Object.keys(definition);
+        this.projection = {};
+        for (const f of this.fields)
+            this.projection[f] = 1;
+    }
+}
+exports.Schema = Schema;
+class Model {
+    constructor(collection, schema) {
+        this.collection = collection;
+        this.schema = schema;
+    }
+    /** Define a model over a collection from a schema definition. */
+    static define(collection, definition) {
+        return new Model(collection, new Schema(definition));
+    }
+    /** The cached projection MongoDB receives (schema fields only). */
+    getProjection() {
+        return this.schema.projection;
+    }
+    /** find with the schema projection pushed down. */
+    async find(filter = {}, options = {}) {
+        return this.collection.find(filter, {
+            ...options,
+            projection: this.schema.projection,
+        });
+    }
+    /** First match, or null. */
+    async findOne(filter = {}, options = {}) {
+        const rows = await this.find(filter, { ...options, limit: 1 });
+        return rows[0] ?? null;
+    }
+    /** Find by _id. Accepts a 24-char hex ObjectId string (Mongoose-style). */
+    async findById(id, options = {}) {
+        // Encode as Extended JSON so the Rust layer casts it to an ObjectId.
+        return this.findOne({ _id: { $oid: id } }, options);
+    }
+}
+exports.Model = Model;

package/dist/shadow.d.ts

@@ -0,0 +1,14 @@
+/** Structural deep-equality via canonical JSON (order-insensitive for objects). */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+export interface Divergence<T> {
+    rust: T[];
+    official: T[];
+}
+/**
+ * Run both implementations concurrently. If results diverge, call `onDivergence`
+ * (e.g. log/metric) but still return the official result. If rumongo throws, the
+ * divergence callback gets the error and the official result is returned.
+ */
+export declare function shadow<T>(rustFn: () => Promise<T[]>, officialFn: () => Promise<T[]>, onDivergence: (info: Divergence<T> & {
+    error?: unknown;
+}) => void): Promise<T[]>;

package/dist/shadow.js

@@ -0,0 +1,53 @@
+"use strict";
+// Shadow mode: run rumongo alongside the official driver, compare results, log
+// divergences — but always return the official result. Lets you validate rumongo
+// in production before cutover without risking responses.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqual = deepEqual;
+exports.shadow = shadow;
+/** Structural deep-equality via canonical JSON (order-insensitive for objects). */
+function deepEqual(a, b) {
+    return canon(a) === canon(b);
+}
+function canon(v) {
+    return JSON.stringify(sortKeys(v));
+}
+// Normalize the official driver's rich BSON types to the Extended-JSON shapes
+// rumongo emits, so equal DATA compares equal regardless of JS class:
+//   ObjectId -> {$oid: hex},  Date -> {$date:{$numberLong: ms}}
+function sortKeys(v) {
+    if (v === null || typeof v !== 'object')
+        return v;
+    if (v instanceof Date)
+        return { $date: { $numberLong: String(v.getTime()) } };
+    const oid = v;
+    if (typeof oid.toHexString === 'function' && oid._bsontype === 'ObjectId') {
+        return { $oid: oid.toHexString() };
+    }
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    const o = v;
+    const out = {};
+    for (const k of Object.keys(o).sort())
+        out[k] = sortKeys(o[k]);
+    return out;
+}
+/**
+ * Run both implementations concurrently. If results diverge, call `onDivergence`
+ * (e.g. log/metric) but still return the official result. If rumongo throws, the
+ * divergence callback gets the error and the official result is returned.
+ */
+async function shadow(rustFn, officialFn, onDivergence) {
+    const [rustSettled, official] = await Promise.all([
+        rustFn().then((r) => ({ ok: true, r }), (error) => ({ ok: false, error })),
+        officialFn(),
+    ]);
+    if (!rustSettled.ok) {
+        onDivergence({ rust: [], official, error: rustSettled.error });
+        return official;
+    }
+    if (!deepEqual(rustSettled.r, official)) {
+        onDivergence({ rust: rustSettled.r, official });
+    }
+    return official;
+}

package/index.d.ts

@@ -0,0 +1,51 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare class MongoClient {
+  /**
+   * Connect to MongoDB. `options` is an optional JSON string with pool/timeout
+   * config: `{ maxPoolSize, minPoolSize, connectTimeoutMs,
+   * serverSelectionTimeoutMs, appName }`. The driver already pools connections;
+   * these expose the knobs.
+   */
+  static connect(uri: string, options?: string | undefined | null): Promise<MongoClient>
+  /**
+   * Terminate background workers and close connections. Call before process
+   * exit: otherwise the driver's topology-monitor tasks keep the runtime
+   * alive and Node will not exit. `immediate(true)` does not wait for live
+   * cursor handles (acceptable at teardown).
+   */
+  close(): Promise<void>
+  /** Eager find: returns one JSON string per document (Phase 3 path). */
+  find(db: string, coll: string, filterJson: string, optsJson: string): Promise<Array<string>>
+  /**
+   * Lazy find (Phase 4): returns `RawDoc` handles holding raw bytes. No values
+   * are parsed until JS reads a field, so the event loop is not blocked by a
+   * deserialize burst on return.
+   */
+  findLazy(db: string, coll: string, filterJson: string, optsJson: string): Promise<Array<RawDoc>>
+  /**
+   * Streaming lazy find (Phase 4): returns a `FindCursor`. Pull batches with
+   * `next_batch()` and process+drop each before the next, so peak live memory
+   * is one batch and GC jitter under concurrency stays low.
+   */
+  findCursor(db: string, coll: string, filterJson: string, optsJson: string): Promise<FindCursor>
+}
+export declare class FindCursor {
+  /**
+   * Next batch of lazy `RawDoc` handles, or `null` when exhausted.
+   * Awaiting this is a real loop yield point, so timers/IO run between batches.
+   */
+  nextBatch(): Promise<Array<RawDoc> | null>
+}
+/** A lazily-parsed MongoDB document backed by raw BSON bytes. */
+export declare class RawDoc {
+  /** Parse and return a single field. `undefined` if absent. */
+  getField(name: string): unknown
+  /** Full parse into a plain JS object (escape hatch for spread/JSON.stringify). */
+  toObject(): object
+  /** Field names without parsing any values. */
+  keys(): Array<string>
+}