albedo-node 0.6.2 → 0.7.2

package/README.md

@@ -8,7 +8,7 @@ This package wraps the core database engine with a concise TypeScript API, ships
 
 - 🧱 Access to the full Albedo bucket API from Node.js or Bun
 - 📦 Precompiled native modules for Linux (glibc & musl), macOS, and arm64/x64
-- 🔁 Generator-based iterators for queries and in-place document transforms
+- 🔁 Generator-based iterators for queries, transforms, and live subscriptions
 - 🔄 Built-in replication callback and apply mechanisms
 - 🧪 TypeScript typings and Bun-based test suite
 
@@ -86,6 +86,48 @@ while (!step.done) {
 }
 ```
 
+### Subscribing to change events
+
+`Bucket.subscribe()` exposes the new oplog-backed subscription API as an async
+generator. It yields individual change events rather than re-scanned documents.
+
+```ts
+const bucket = Bucket.open("./example.bucket", {
+  wal: true,
+  write_durability: "all",
+});
+
+for await (const event of bucket.subscribe<{ name: string }>(
+  where("name", { $eq: "Ada" }),
+  { pollingTimeout: 50, batchSize: 64 },
+)) {
+  console.log(event.op, event.seqno, event.doc);
+
+  if (event.op === "delete") {
+    console.log("deleted", event.doc_id.toString());
+  }
+}
+```
+
+Each yielded event has this shape:
+
+```ts
+type SubscriptionEvent<T = unknown> = {
+  seqno: bigint;
+  op: "insert" | "update" | "delete";
+  doc_id: ObjectId;
+  ts: bigint;
+  doc?: T;
+};
+```
+
+Notes:
+
+- Subscriptions require WAL mode to be active.
+- `doc` is present for inline insert and update payloads.
+- Delete events still include `doc_id`, even when `doc` is absent.
+- The generator closes the native subscription automatically when iteration stops.
+
 ### Replication
 
 ```ts
@@ -146,6 +188,7 @@ Serialized documents that contain `_id` fields with a BSON ObjectId will be revi
   - `insert(doc: object | Uint8Array)`
   - `delete(query?: object | Query)`
   - `list<T>(query?: object | Query): Generator<T>`
+  - `subscribe<T>(query?: object | Query, options?: { pollingTimeout?: number; batchSize?: number }): AsyncGenerator<SubscriptionEvent<T>>`
   - `transformIterator<T>(query?: object | Query): Generator<T, undefined, object | null>`
   - `ensureIndex(name: string, options: { unique: boolean; sparse: boolean; reverse: boolean })`
   - `dropIndex(name: string)`
@@ -154,6 +197,13 @@ Serialized documents that contain `_id` fields with a BSON ObjectId will be revi
   - `applyReplicationBatch(batch: Uint8Array)`
   - accepts raw BSON `Uint8Array` payloads anywhere a query or document object is expected
 
+- `SubscriptionEvent<T>`
+  - `seqno: bigint`
+  - `op: "insert" | "update" | "delete"`
+  - `doc_id: ObjectId`
+  - `ts: bigint`
+  - `doc?: T`
+
 - `Query`
   - `where(field, filter)` chains field predicates (e.g. `{ $eq: value }`, `{ $gt: 10 }`)
   - `sortBy(field, direction?)` sets sort order

package/dist/index.d.ts

@@ -1,9 +1,19 @@
 type ByteBuffer = Uint8Array;
+type BucketHandle = object;
+type ListIteratorHandle = object;
+type TransformIteratorHandle = object;
+type SubscriptionHandle = object;
 interface IndexOptions {
     unique: boolean;
     sparse: boolean;
     reverse: boolean;
 }
+interface IndexInfo {
+    name: string;
+    unique: boolean;
+    sparse: boolean;
+    reverse: boolean;
+}
 interface ObjectIdInstance {
     buffer: ByteBuffer;
     toString(): string;
@@ -12,6 +22,20 @@ interface ObjectIdConstructor {
     new (buffer?: ByteBuffer): ObjectIdInstance;
     fromString(str: string): ObjectIdInstance;
 }
+export interface SubscriptionEvent<T = unknown> {
+    seqno: bigint;
+    op: "insert" | "update" | "delete";
+    doc_id: ObjectIdInstance;
+    ts: bigint;
+    doc?: T;
+}
+interface SubscriptionBatch<T = unknown> {
+    batch: Array<SubscriptionEvent<T>>;
+}
+export interface SubscribeOptions {
+    pollingTimeout?: number;
+    batchSize?: number;
+}
 /**
  * Controls when fsync is called to guarantee write durability.
  */
@@ -34,11 +58,36 @@ interface OpenBucketOptions {
     write_durability?: WriteDurability;
     read_durability?: ReadDurability;
 }
-export declare const albedo: any;
+interface AlbedoModule {
+    ObjectId: ObjectIdConstructor;
+    serialize(value: unknown): Uint8Array;
+    deserialize<T = unknown>(data: ByteBuffer): T;
+    open(path: string): BucketHandle;
+    open_with_options(path: string, options: OpenBucketOptions): BucketHandle;
+    close(bucket: BucketHandle): void;
+    list(bucket: BucketHandle, query: object): ListIteratorHandle;
+    listClose(cursor: ListIteratorHandle): void;
+    listData(cursor: ListIteratorHandle): unknown | null;
+    insert(bucket: BucketHandle, doc: ByteBuffer | object): void;
+    ensureIndex(bucket: BucketHandle, name: string, options: IndexOptions): void;
+    listIndexes(bucket: BucketHandle): Record<string, IndexInfo>;
+    dropIndex(bucket: BucketHandle, name: string): void;
+    delete(bucket: BucketHandle, query: object): void;
+    transform(bucket: BucketHandle, query: object): TransformIteratorHandle;
+    transformClose(iter: TransformIteratorHandle): void;
+    transformData(iter: TransformIteratorHandle): unknown | null;
+    transformApply(iter: TransformIteratorHandle, replace: ByteBuffer | object | null): void;
+    subscribe(bucket: BucketHandle, query: object): SubscriptionHandle;
+    subscribePoll<T = unknown>(sub: SubscriptionHandle, maxEvents: number): SubscriptionBatch<T> | null;
+    subscribeClose(sub: SubscriptionHandle): void;
+    setReplicationCallback(bucket: BucketHandle, callback: (data: Uint8Array) => void): void;
+    applyReplicationBatch(bucket: BucketHandle, data: ByteBuffer): void;
+}
+export declare const albedo: AlbedoModule;
 export default albedo;
 export declare const BSON: {
-    serialize: any;
-    deserialize: any;
+    serialize: (value: unknown) => Uint8Array;
+    deserialize: <T = unknown>(data: ByteBuffer) => T;
 };
 /**
  * Native ObjectId class constructor.
@@ -127,7 +176,7 @@ export declare class Bucket {
      * console.log(bucket.indexes);
      * ```
      */
-    get indexes(): any;
+    get indexes(): Record<string, IndexInfo>;
     /**
      * Create or update an index on a field.
      * @param name - index name (field path)
@@ -159,29 +208,26 @@ export declare class Bucket {
      */
     list<T>(query?: object | Query): Generator<T>;
     /**
-     * Async iterator that continuously polls for documents matching the
-     * optional query. Unlike `list`, when there are no more results the
-     * iterator waits for `pollingTimeout` milliseconds and retries,
-     * making it suitable for watching a bucket for new data.
+     * Async iterator that continuously polls a change subscription.
      *
-     * The native cursor is closed automatically when the consumer breaks
-     * out of the loop or the iterator is otherwise disposed.
+     * The generator yields individual oplog events rather than rescanned
+     * documents, and automatically closes the native subscription when the
+     * consumer stops iterating.
      *
      * @param query - filter or `Query` object
      * @param options - polling configuration
-     * @param options.pollingTimeout - ms to wait before retrying when
-     *   `listData` returns `null` (default `50`)
-     * @yields each document deserialized from the bucket
+     * @param options.pollingTimeout - ms to wait before retrying when the
+     *   subscription is idle (default `50`)
+     * @param options.batchSize - maximum number of change events to pull per
+     *   native poll (default `64`)
      * @example
      * ```ts
-     * for await (const user of bucket.stream<User>(where('active', { $eq: true }))) {
-     *   console.log(user);
+     * for await (const event of bucket.subscribe<User>(where('active', { $eq: true }))) {
+     *   console.log(event.op, event.doc);
      * }
      * ```
      */
-    stream<T>(query?: object | Query, options?: {
-        pollingTimeout?: number;
-    }): AsyncGenerator<T>;
+    subscribe<T>(query?: object | Query, options?: SubscribeOptions): AsyncGenerator<SubscriptionEvent<T>>;
     /**
      * Collect all documents matching the optional query into an array.
      * @param query - filter or `Query` object

package/dist/index.js

@@ -184,34 +184,36 @@ class Bucket {
         }
     }
     /**
-     * Async iterator that continuously polls for documents matching the
-     * optional query. Unlike `list`, when there are no more results the
-     * iterator waits for `pollingTimeout` milliseconds and retries,
-     * making it suitable for watching a bucket for new data.
+     * Async iterator that continuously polls a change subscription.
      *
-     * The native cursor is closed automatically when the consumer breaks
-     * out of the loop or the iterator is otherwise disposed.
+     * The generator yields individual oplog events rather than rescanned
+     * documents, and automatically closes the native subscription when the
+     * consumer stops iterating.
      *
      * @param query - filter or `Query` object
      * @param options - polling configuration
-     * @param options.pollingTimeout - ms to wait before retrying when
-     *   `listData` returns `null` (default `50`)
-     * @yields each document deserialized from the bucket
+     * @param options.pollingTimeout - ms to wait before retrying when the
+     *   subscription is idle (default `50`)
+     * @param options.batchSize - maximum number of change events to pull per
+     *   native poll (default `64`)
      * @example
      * ```ts
-     * for await (const user of bucket.stream<User>(where('active', { $eq: true }))) {
-     *   console.log(user);
+     * for await (const event of bucket.subscribe<User>(where('active', { $eq: true }))) {
+     *   console.log(event.op, event.doc);
      * }
      * ```
      */
-    async *stream(query, options) {
+    async *subscribe(query, options) {
         const pollingTimeout = options?.pollingTimeout ?? 50;
-        const cursor = exports.albedo.list(this.handle, Bucket.convertToQuery(query));
+        const batchSize = options?.batchSize ?? 64;
+        const subscription = exports.albedo.subscribe(this.handle, Bucket.convertToQuery(query));
         try {
             while (true) {
-                const data = exports.albedo.listData(cursor);
-                if (data !== null) {
-                    yield data;
+                const batch = exports.albedo.subscribePoll(subscription, batchSize);
+                if (batch !== null) {
+                    for (const event of batch.batch) {
+                        yield event;
+                    }
                 }
                 else {
                     await new Promise((r) => setTimeout(r, pollingTimeout));
@@ -219,7 +221,7 @@ class Bucket {
             }
         }
         finally {
-            exports.albedo.listClose(cursor);
+            exports.albedo.subscribeClose(subscription);
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "albedo-node",
-  "version": "0.6.2",
+  "version": "0.7.2",
   "description": "High-performance embedded database for Node.js with native bindings, BSON support, indexing, and replication",
   "keywords": [
     "albedo",