albedo-node 0.6.3 → 0.8.1

package/README.md

@@ -8,8 +8,8 @@ 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
-- 🔄 Built-in replication callback and apply mechanisms
+- 🔁 Generator-based iterators for queries, transforms, and live subscriptions
+- 🔄 WAL-based replication helpers with explicit cursors and batches
 - 🧪 TypeScript typings and Bun-based test suite
 
 ## Installation
@@ -86,28 +86,81 @@ while (!step.done) {
 }
 ```
 
-### Replication
+### 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
-const primary = Bucket.open("./primary.bucket");
-const replica = Bucket.open("./replica.bucket");
+type SubscriptionEvent<T = unknown> = {
+  seqno: bigint;
+  op: "insert" | "update" | "delete";
+  doc_id: ObjectId;
+  ts: bigint;
+  doc?: T;
+};
+```
+
+Notes:
 
-const batches: Uint8Array[] = [];
-primary.setReplicationCallback((data) => {
-  batches.push(data);
+- 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
+const primary = Bucket.open("./primary.bucket", {
+  wal: true,
+  write_durability: "all",
+});
+const replica = Bucket.open("./replica.bucket", {
+  wal: true,
+  write_durability: "all",
 });
 
+const cursor = primary.replicationCursor();
+
 primary.insert({ name: "Replica", version: 1 });
-primary.close();
 
-// Apply the first batch to the replica bucket
-if (batches.length > 0) {
-  replica.applyReplicationBatch(batches[0]);
+const batch = primary.readReplicationBatch(cursor);
+if (batch) {
+  const nextCursor = replica.applyReplicationBatch(batch);
+  console.log(nextCursor.next_frame_index);
 }
 
+primary.close();
 replica.close();
 ```
 
+Notes:
+
+- Replication requires WAL mode to be enabled on both buckets.
+- `replicationCursor()` snapshots the current position in the WAL stream.
+- `readReplicationBatch(cursor, maxBytes?)` returns `null` when there is nothing new to send.
+- `applyReplicationBatch(batch)` applies the batch and returns the replica's new cursor.
+
 ## Query objects and BSON payloads
 
 Most bucket operations accept either:
@@ -139,21 +192,44 @@ Serialized documents that contain `_id` fields with a BSON ObjectId will be revi
 ## API reference
 
 - `default` export — raw Albedo native module
-  - `ObjectId`, `serialize`, `deserialize`, `open`, `close`, `insert`, `delete`, `list`, `transform`, `setReplicationCallback`, etc.
+  - `ObjectId`, `serialize`, `deserialize`, `open`, `open_with_options`, `close`, `insert`, `checkpoint`, `delete`, `list`, `transform`, `replicationCursor`, `readReplicationBatch`, `applyReplicationBatch`, etc.
 - `BSON.serialize(value)` / `BSON.deserialize(bytes)` — helper wrappers
 - `Bucket`
-  - `static open(path: string): Bucket`
+  - `static open(path: string, options?: OpenBucketOptions): Bucket`
   - `insert(doc: object | Uint8Array)`
+  - `checkpoint()`
   - `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>`
+  - `transform<T>(query, fn)` / `update<T>(query, fn)`
+  - `all<T>(query?)` / `one<T>(query?)`
+  - `beginTransaction()` / `tx(fn)`
   - `ensureIndex(name: string, options: { unique: boolean; sparse: boolean; reverse: boolean })`
   - `dropIndex(name: string)`
   - `indexes: Record<string, { name: string; unique: boolean; sparse: boolean; reverse: boolean }>`
-  - `setReplicationCallback(cb: (data: Uint8Array) => void)`
-  - `applyReplicationBatch(batch: Uint8Array)`
+  - `replicationCursor(): { generation: bigint; next_frame_index: bigint }`
+  - `readReplicationBatch(cursor, maxBytes?): Uint8Array | null`
+  - `applyReplicationBatch(batch: Uint8Array): { generation: bigint; next_frame_index: bigint }`
   - accepts raw BSON `Uint8Array` payloads anywhere a query or document object is expected
 
+- `OpenBucketOptions`
+  - `buildIdIndex?: boolean`
+  - `mode?: string`
+  - `auto_vaccuum?: boolean`
+  - `page_cache_capacity?: number`
+  - `wal?: boolean`
+  - `write_durability?: "all" | "manual" | { periodic: number }`
+  - `read_durability?: "shared" | "process"`
+  - `wal_auto_checkpoint?: (defaults to 1000 pages)` 
+
+- `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,24 @@
 type ByteBuffer = Uint8Array;
+type BucketHandle = object;
+type TransactionHandle = object;
+type ListIteratorHandle = object;
+type TransformIteratorHandle = object;
+type SubscriptionHandle = object;
+export interface ReplicationCursor {
+    generation: bigint;
+    next_frame_index: bigint;
+}
 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 +27,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 +63,45 @@ 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;
+    checkpoint(bucket: BucketHandle): void;
+    transactionBegin(bucket: BucketHandle): TransactionHandle;
+    transactionInsert(tx: TransactionHandle, 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;
+    transactionDelete(tx: TransactionHandle, query: object): void;
+    transform(bucket: BucketHandle, query: object): TransformIteratorHandle;
+    transactionTransform(tx: TransactionHandle, query: object): TransformIteratorHandle;
+    transformClose(iter: TransformIteratorHandle): void;
+    transformData(iter: TransformIteratorHandle): unknown | null;
+    transformApply(iter: TransformIteratorHandle, replace: ByteBuffer | object | null): void;
+    transactionCommit(tx: TransactionHandle): void;
+    transactionRollback(tx: TransactionHandle): void;
+    transactionClose(tx: TransactionHandle): void;
+    subscribe(bucket: BucketHandle, query: object): SubscriptionHandle;
+    subscribePoll<T = unknown>(sub: SubscriptionHandle, maxEvents: number): SubscriptionBatch<T> | null;
+    subscribeClose(sub: SubscriptionHandle): void;
+    replicationCursor(bucket: BucketHandle): ReplicationCursor;
+    readReplicationBatch(bucket: BucketHandle, cursor: ReplicationCursor, maxBytes: number): ByteBuffer | null;
+    applyReplicationBatch(bucket: BucketHandle, data: ByteBuffer): ReplicationCursor;
+}
+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.
@@ -50,6 +113,50 @@ export declare const BSON: {
  * ```
  */
 export declare const ObjectId: ObjectIdConstructor;
+type QueryInput = object | Query;
+type TransformReplacement<T extends object> = T | ByteBuffer | null;
+/**
+ * Wrapper around a native transaction handle providing
+ * write operations that are committed or rolled back together.
+ */
+export declare class Transaction {
+    private handle;
+    constructor(handle: object);
+    private get nativeHandle();
+    /**
+     * Insert a document or raw byte buffer into the transaction.
+     */
+    insert(doc: object | ByteBuffer): void;
+    /**
+     * Delete documents matching the query from the transaction.
+     */
+    delete(query?: QueryInput): void;
+    /**
+     * Generator that allows reading and modifying matching documents
+     * within the transaction.
+     */
+    transformIterator<T extends object>(query?: QueryInput): Generator<T, undefined, TransformReplacement<T>>;
+    /**
+     * Apply a transformation function to matching documents in the transaction.
+     */
+    transform<T extends object>(query: QueryInput | undefined, fn: (doc: T) => TransformReplacement<T>): void;
+    /**
+     * Alias for `transform` that reads more naturally for document updates.
+     */
+    update<T extends object>(query: QueryInput | undefined, fn: (doc: T) => TransformReplacement<T>): void;
+    /**
+     * Commit the transaction.
+     */
+    commit(): void;
+    /**
+     * Roll back the transaction.
+     */
+    rollback(): void;
+    /**
+     * Close the transaction and release native resources.
+     */
+    close(): void;
+}
 /**
  * Wrapper around a native Albedo bucket handle providing
  * methods for CRUD operations, indexing, iteration, and
@@ -108,6 +215,21 @@ export declare class Bucket {
      * ```
      */
     insert(doc: object | ByteBuffer): void;
+    /**
+     * Flush buffered bucket state through the native checkpoint mechanism.
+     */
+    checkpoint(): void;
+    /**
+     * Begin a manual transaction on this bucket.
+     */
+    beginTransaction(): Transaction;
+    /**
+     * Run a callback inside a transaction and commit it on success.
+     *
+     * If the callback throws, the transaction is rolled back before the
+     * original error is re-thrown.
+     */
+    tx<T>(fn: (tx: Transaction) => T): T;
     /**
      * Delete documents matching the query. If no query is provided,
      * all documents will be removed.
@@ -127,7 +249,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 +281,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
@@ -229,7 +348,7 @@ export declare class Bucket {
      * }
      * ```
      */
-    transformIterator<T>(query?: object | Query): Generator<T, undefined, null | object>;
+    transformIterator<T extends object>(query?: object | Query): Generator<T, undefined, TransformReplacement<T>>;
     /**
      * Apply a transformation function to each document matching the
      * provided query. The predicate receives the current document and
@@ -248,19 +367,13 @@ export declare class Bucket {
      * });
      * ```
      */
-    transform<T extends object>(query: object | Query | undefined, fn: (doc: T) => T | null): void;
+    transform<T extends object>(query: object | Query | undefined, fn: (doc: T) => TransformReplacement<T>): void;
     /**
-     * Register a callback to receive replication data produced by the
-     * bucket.
-     * @param callback - invoked with raw replication bytes
-     * @example
-     * ```ts
-     * bucket.setReplicationCallback(bytes => {
-     *   console.log('got replication', bytes.length);
-     * });
-     * ```
+     * Alias for `transform` that reads more naturally for document updates.
      */
-    setReplicationCallback(callback: (data: Uint8Array) => void): void;
+    update<T extends object>(query: object | Query | undefined, fn: (doc: T) => TransformReplacement<T>): void;
+    replicationCursor(): ReplicationCursor;
+    readReplicationBatch(cursor: ReplicationCursor, maxBytes?: number): Uint8Array | null;
     /**
      * Apply a batch of replication operations to this bucket.
      * @param data - bytes produced by another bucket's replication
@@ -269,7 +382,7 @@ export declare class Bucket {
      * bucket.applyReplicationBatch(remoteBytes);
      * ```
      */
-    applyReplicationBatch(data: Uint8Array): void;
+    applyReplicationBatch(data: Uint8Array): ReplicationCursor;
 }
 type BSONValue = any;
 type FilterOperators = {

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Query = exports.Bucket = exports.ObjectId = exports.BSON = exports.albedo = void 0;
+exports.Query = exports.Bucket = exports.Transaction = exports.ObjectId = exports.BSON = exports.albedo = void 0;
 exports.where = where;
 const detect_libc_1 = require("detect-libc");
 function getNativeBinding() {
@@ -47,6 +47,106 @@ exports.BSON = {
  * ```
  */
 exports.ObjectId = exports.albedo.ObjectId;
+function convertToQuery(query) {
+    if (query instanceof Query) {
+        return query.query;
+    }
+    return query || {};
+}
+function* iterateTransform(iter) {
+    try {
+        let data;
+        while ((data = exports.albedo.transformData(iter)) !== undefined) {
+            const newDoc = yield data;
+            exports.albedo.transformApply(iter, newDoc);
+        }
+    }
+    finally {
+        exports.albedo.transformClose(iter);
+    }
+}
+function applyTransform(iter, fn) {
+    try {
+        let data;
+        while ((data = exports.albedo.transformData(iter)) !== undefined) {
+            exports.albedo.transformApply(iter, fn(data));
+        }
+    }
+    finally {
+        exports.albedo.transformClose(iter);
+    }
+}
+function aggregateErrors(message, errors) {
+    return new AggregateError(errors, message);
+}
+/**
+ * Wrapper around a native transaction handle providing
+ * write operations that are committed or rolled back together.
+ */
+class Transaction {
+    handle;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    get nativeHandle() {
+        if (this.handle === null) {
+            throw new Error("Transaction is closed");
+        }
+        return this.handle;
+    }
+    /**
+     * Insert a document or raw byte buffer into the transaction.
+     */
+    insert(doc) {
+        exports.albedo.transactionInsert(this.nativeHandle, doc);
+    }
+    /**
+     * Delete documents matching the query from the transaction.
+     */
+    delete(query) {
+        exports.albedo.transactionDelete(this.nativeHandle, convertToQuery(query));
+    }
+    /**
+     * Generator that allows reading and modifying matching documents
+     * within the transaction.
+     */
+    transformIterator(query) {
+        return iterateTransform(exports.albedo.transactionTransform(this.nativeHandle, convertToQuery(query)));
+    }
+    /**
+     * Apply a transformation function to matching documents in the transaction.
+     */
+    transform(query, fn) {
+        applyTransform(exports.albedo.transactionTransform(this.nativeHandle, convertToQuery(query)), fn);
+    }
+    /**
+     * Alias for `transform` that reads more naturally for document updates.
+     */
+    update(query, fn) {
+        this.transform(query, fn);
+    }
+    /**
+     * Commit the transaction.
+     */
+    commit() {
+        exports.albedo.transactionCommit(this.nativeHandle);
+    }
+    /**
+     * Roll back the transaction.
+     */
+    rollback() {
+        exports.albedo.transactionRollback(this.nativeHandle);
+    }
+    /**
+     * Close the transaction and release native resources.
+     */
+    close() {
+        const handle = this.nativeHandle;
+        exports.albedo.transactionClose(handle);
+        this.handle = null;
+    }
+}
+exports.Transaction = Transaction;
 /**
  * Wrapper around a native Albedo bucket handle providing
  * methods for CRUD operations, indexing, iteration, and
@@ -114,6 +214,75 @@ class Bucket {
     insert(doc) {
         exports.albedo.insert(this.handle, doc);
     }
+    /**
+     * Flush buffered bucket state through the native checkpoint mechanism.
+     */
+    checkpoint() {
+        exports.albedo.checkpoint(this.handle);
+    }
+    /**
+     * Begin a manual transaction on this bucket.
+     */
+    beginTransaction() {
+        return new Transaction(exports.albedo.transactionBegin(this.handle));
+    }
+    /**
+     * Run a callback inside a transaction and commit it on success.
+     *
+     * If the callback throws, the transaction is rolled back before the
+     * original error is re-thrown.
+     */
+    tx(fn) {
+        const tx = this.beginTransaction();
+        let result;
+        try {
+            result = fn(tx);
+        }
+        catch (error) {
+            try {
+                tx.rollback();
+            }
+            catch (rollbackError) {
+                try {
+                    tx.close();
+                }
+                catch (closeError) {
+                    throw aggregateErrors("Transaction failed, rollback failed, and close failed", [error, rollbackError, closeError]);
+                }
+                throw aggregateErrors("Transaction failed and rollback failed", [
+                    error,
+                    rollbackError,
+                ]);
+            }
+            try {
+                tx.close();
+            }
+            catch (closeError) {
+                throw aggregateErrors("Transaction failed and close failed", [
+                    error,
+                    closeError,
+                ]);
+            }
+            throw error;
+        }
+        try {
+            tx.commit();
+        }
+        catch (commitError) {
+            try {
+                tx.close();
+            }
+            catch (closeError) {
+                throw aggregateErrors("Transaction commit and close both failed", [
+                    commitError,
+                    closeError,
+                ]);
+            }
+            throw commitError;
+        }
+        tx.close();
+        return result;
+    }
     /**
      * Delete documents matching the query. If no query is provided,
      * all documents will be removed.
@@ -126,7 +295,7 @@ class Bucket {
      * ```
      */
     delete(query) {
-        exports.albedo.delete(this.handle, Bucket.convertToQuery(query));
+        exports.albedo.delete(this.handle, convertToQuery(query));
     }
     /**
      * Retrieve information about all indexes defined on the bucket.
@@ -172,7 +341,7 @@ class Bucket {
      * ```
      */
     *list(query) {
-        const cursor = exports.albedo.list(this.handle, Bucket.convertToQuery(query));
+        const cursor = exports.albedo.list(this.handle, convertToQuery(query));
         try {
             let data;
             while ((data = exports.albedo.listData(cursor)) !== null) {
@@ -184,34 +353,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, 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 +390,7 @@ class Bucket {
             }
         }
         finally {
-            exports.albedo.listClose(cursor);
+            exports.albedo.subscribeClose(subscription);
         }
     }
     /**
@@ -260,10 +431,7 @@ class Bucket {
      * ```
      */
     static convertToQuery(query) {
-        if (query instanceof Query) {
-            return query.query;
-        }
-        return query || {};
+        return convertToQuery(query);
     }
     /**
      * Generator that allows reading and optionally modifying each
@@ -282,18 +450,7 @@ class Bucket {
      * ```
      */
     *transformIterator(query) {
-        const queryObj = Bucket.convertToQuery(query);
-        const iter = exports.albedo.transform(this.handle, queryObj);
-        try {
-            let data;
-            while ((data = exports.albedo.transformData(iter)) !== undefined) {
-                const newDoc = yield data;
-                exports.albedo.transformApply(iter, newDoc);
-            }
-        }
-        finally {
-            exports.albedo.transformClose(iter);
-        }
+        yield* iterateTransform(exports.albedo.transform(this.handle, convertToQuery(query)));
     }
     /**
      * Apply a transformation function to each document matching the
@@ -314,31 +471,19 @@ class Bucket {
      * ```
      */
     transform(query, fn) {
-        const queryObj = Bucket.convertToQuery(query);
-        const iter = exports.albedo.transform(this.handle, queryObj);
-        try {
-            let data;
-            while ((data = exports.albedo.transformData(iter)) !== undefined) {
-                exports.albedo.transformApply(iter, fn(data));
-            }
-        }
-        finally {
-            exports.albedo.transformClose(iter);
-        }
+        applyTransform(exports.albedo.transform(this.handle, convertToQuery(query)), fn);
     }
     /**
-     * Register a callback to receive replication data produced by the
-     * bucket.
-     * @param callback - invoked with raw replication bytes
-     * @example
-     * ```ts
-     * bucket.setReplicationCallback(bytes => {
-     *   console.log('got replication', bytes.length);
-     * });
-     * ```
+     * Alias for `transform` that reads more naturally for document updates.
      */
-    setReplicationCallback(callback) {
-        exports.albedo.setReplicationCallback(this.handle, callback);
+    update(query, fn) {
+        this.transform(query, fn);
+    }
+    replicationCursor() {
+        return exports.albedo.replicationCursor(this.handle);
+    }
+    readReplicationBatch(cursor, maxBytes = 0) {
+        return exports.albedo.readReplicationBatch(this.handle, cursor, maxBytes);
     }
     /**
      * Apply a batch of replication operations to this bucket.
@@ -349,7 +494,7 @@ class Bucket {
      * ```
      */
     applyReplicationBatch(data) {
-        exports.albedo.applyReplicationBatch(this.handle, data);
+        return exports.albedo.applyReplicationBatch(this.handle, data);
     }
 }
 exports.Bucket = Bucket;

package/package.json

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