albedo-node 0.7.2 → 0.8.2

package/README.md

@@ -9,7 +9,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, transforms, and live subscriptions
-- 🔄 Built-in replication callback and apply mechanisms
+- 🔄 WAL-based replication helpers with explicit cursors and batches
 - 🧪 TypeScript typings and Bun-based test suite
 
 ## Installation
@@ -75,6 +75,47 @@ bucket.close();
 
 You can chain multiple `where` calls or combine them with `sortBy` and `sector`. For quick one-off predicates, the standalone `where(field, filter)` helper returns a `Query` instance that slots into any method accepting a query.
 
+Logical groups are available as both instance methods and static constructors:
+
+```ts
+import { Query, where } from "albedo-node";
+
+const visibleUsers = Query.or(
+  where("role", "admin"),
+  Query.and(
+    where("role", "user"),
+    where("verified", true),
+  ),
+).nor(
+  where("deleted", true),
+);
+
+for (const doc of bucket.list(visibleUsers)) {
+  console.log(doc);
+}
+```
+
+This produces a query equivalent to:
+
+```ts
+{
+  query: {
+    $or: [
+      { role: "admin" },
+      {
+        $and: [
+          { role: "user" },
+          { verified: true },
+        ],
+      },
+    ],
+    $nor: [
+      { deleted: true },
+    ],
+  },
+}
+```
+
 ### Transforming documents in place
 
 ```ts
@@ -131,25 +172,36 @@ Notes:
 ### Replication
 
 ```ts
-const primary = Bucket.open("./primary.bucket");
-const replica = Bucket.open("./replica.bucket");
-
-const batches: Uint8Array[] = [];
-primary.setReplicationCallback((data) => {
-  batches.push(data);
+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:
@@ -162,8 +214,22 @@ Regardless of which form you use, the structure mirrors the underlying Albedo qu
 
 - `{ query: { field: value } }` — equality filters
 - `{ query: { age: { "$gt": 40 } } }` — comparison operators
+- `{ query: { $or: [{ role: "admin" }, { public: true }], deleted: false } }` — logical groups mixed with leaf filters
 - `{ query: { _id: someId }, sector: { limit: 10, offset: 0 } }` — pagination controls
 
+Supported field operators in this binding include:
+
+- `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`
+- `$in`, `$between`
+- `$startsWith`, `$endsWith`
+- `$exists`, `$notExists`
+
+Logical operators supported inside `query` are:
+
+- `$or`
+- `$and`
+- `$nor`
+
 For the exhaustive list of operators and document shapes, consult the [Albedo Query reference](https://github.com/klirix/albedo#readme). Whatever BSON document the core engine accepts can be provided here either as a plain object or as prebuilt BSON bytes.
 
 ### ObjectId support
@@ -181,22 +247,37 @@ 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"`
@@ -206,8 +287,14 @@ Serialized documents that contain `_id` fields with a BSON ObjectId will be revi
 
 - `Query`
   - `where(field, filter)` chains field predicates (e.g. `{ $eq: value }`, `{ $gt: 10 }`)
+  - `or(...clauses)` adds an `$or` group
+  - `and(...clauses)` adds an `$and` group
+  - `nor(...clauses)` adds a `$nor` group
   - `sortBy(field, direction?)` sets sort order
   - `sector(offset?, limit?)` applies pagination window
+  - `static or(...clauses): Query` creates a query with an `$or` group
+  - `static and(...clauses): Query` creates a query with an `$and` group
+  - `static nor(...clauses): Query` creates a query with a `$nor` group
 
 - `where(field, filter): Query` — convenience helper that creates a single-field `Query`
 

package/dist/index.d.ts

@@ -1,8 +1,13 @@
 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;
@@ -69,19 +74,28 @@ interface AlbedoModule {
     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;
-    setReplicationCallback(bucket: BucketHandle, callback: (data: Uint8Array) => void): void;
-    applyReplicationBatch(bucket: BucketHandle, data: ByteBuffer): 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;
@@ -99,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
@@ -157,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.
@@ -275,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
@@ -294,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
@@ -315,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) {
@@ -206,7 +375,7 @@ class Bucket {
     async *subscribe(query, options) {
         const pollingTimeout = options?.pollingTimeout ?? 50;
         const batchSize = options?.batchSize ?? 64;
-        const subscription = exports.albedo.subscribe(this.handle, Bucket.convertToQuery(query));
+        const subscription = exports.albedo.subscribe(this.handle, convertToQuery(query));
         try {
             while (true) {
                 const batch = exports.albedo.subscribePoll(subscription, batchSize);
@@ -262,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
@@ -284,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
@@ -316,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.
@@ -351,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.7.2",
+  "version": "0.8.2",
   "description": "High-performance embedded database for Node.js with native bindings, BSON support, indexing, and replication",
   "keywords": [
     "albedo",