albedo-node 0.5.4 → 0.5.6

package/README.md

@@ -0,0 +1,183 @@
+# albedo-node
+
+Native Node.js/Bun bindings for the [Albedo](https://github.com/klirix/albedo) embedded document database.
+
+This package wraps the core database engine with a concise TypeScript API, ships prebuilt binaries for common platforms, and exposes BSON helpers plus replication utilities so you can embed Albedo buckets directly in your applications.
+
+## Features
+
+- 🧱 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
+- 🧪 TypeScript typings and Bun-based test suite
+
+## Installation
+
+Install with your preferred package manager (Node.js 18+ or Bun 1.0+ recommended):
+
+```bash
+npm install albedo-node
+```
+
+```bash
+pnpm add albedo-node
+```
+
+```bash
+bun add albedo-node
+```
+
+The published package includes native binaries under `native/`. When running on an unsupported platform, or if you prefer to build locally, install [Zig 0.15.x](https://ziglang.org/download/) and run `bun run build` to compile the binding.
+
+## Quick start
+
+```ts
+import albedo, { BSON, Bucket, where } from "albedo-node";
+
+// Open or create a bucket on disk
+const bucket = Bucket.open("./example.bucket");
+
+// Insert JavaScript objects or pre-serialized BSON buffers
+bucket.insert({ name: "Ada", skills: ["math", "computing"] });
+
+const serialized = BSON.serialize({ name: "Alan", skills: ["logic", "cryptanalysis"] });
+bucket.insert(serialized);
+
+// List documents using a generator with the fluent `where` helper
+for (const doc of bucket.list(where("name", { $eq: "Ada" }))) {
+  console.log(doc);
+}
+
+bucket.close();
+```
+
+### Fluent query helpers
+
+Use the fluent `Query` builder when you need more than a single-field filter:
+
+```ts
+import { Bucket, Query } from "albedo-node";
+
+const bucket = Bucket.open("./example.bucket");
+
+const adults = new Query()
+  .where("age", { $gte: 21 })
+  .sortBy("_id", "asc")
+  .sector(0, 50);
+
+for (const doc of bucket.list(adults)) {
+  console.log(doc);
+}
+
+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.
+
+### Transforming documents in place
+
+```ts
+const iter = bucket.transformIterator({ query: { name: "Ada" } });
+let step = iter.next();
+while (!step.done) {
+  const doc = step.value as { name: string; skills: string[] };
+  step = iter.next({ ...doc, skills: [...doc.skills, "analytics"] });
+}
+```
+
+### Replication
+
+```ts
+const primary = Bucket.open("./primary.bucket");
+const replica = Bucket.open("./replica.bucket");
+
+const batches: Uint8Array[] = [];
+primary.setReplicationCallback((data) => {
+  batches.push(data);
+});
+
+primary.insert({ name: "Replica", version: 1 });
+primary.close();
+
+// Apply the first batch to the replica bucket
+if (batches.length > 0) {
+  replica.applyReplicationBatch(batches[0]);
+}
+
+replica.close();
+```
+
+## Query objects and BSON payloads
+
+Most bucket operations accept either:
+
+- Plain JavaScript objects that will be converted to BSON automatically, or
+- Raw `Uint8Array` buffers containing BSON documents that you have serialized yourself, or
+- Instances of the fluent `Query` builder (including values produced by the `where()` helper).
+
+Regardless of which form you use, the structure mirrors the underlying Albedo query language. Common patterns include:
+
+- `{ query: { field: value } }` — equality filters
+- `{ query: { age: { "$gt": 40 } } }` — comparison operators
+- `{ query: { _id: someId }, sector: { limit: 10, offset: 0 } }` — pagination controls
+
+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
+
+The module exposes `albedo.ObjectId`, compatible with the BSON 12-byte identifier:
+
+```ts
+const id = new albedo.ObjectId();
+const hex = id.toString();
+const parsed = albedo.ObjectId.fromString(hex);
+```
+
+Serialized documents that contain `_id` fields with a BSON ObjectId will be revived as `ObjectId` instances when deserialized.
+
+## API reference
+
+- `default` export — raw Albedo native module
+  - `ObjectId`, `serialize`, `deserialize`, `open`, `close`, `insert`, `delete`, `list`, `transform`, `setReplicationCallback`, etc.
+- `BSON.serialize(value)` / `BSON.deserialize(bytes)` — helper wrappers
+- `Bucket`
+  - `static open(path: string): Bucket`
+  - `insert(doc: object | Uint8Array)`
+  - `delete(query?: object | Query)`
+  - `list<T>(query?: object | Query): Generator<T>`
+  - `transformIterator<T>(query?: object | Query): Generator<T, undefined, object | null>`
+  - `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)`
+  - accepts raw BSON `Uint8Array` payloads anywhere a query or document object is expected
+
+- `Query`
+  - `where(field, filter)` chains field predicates (e.g. `{ $eq: value }`, `{ $gt: 10 }`)
+  - `sortBy(field, direction?)` sets sort order
+  - `sector(offset?, limit?)` applies pagination window
+
+- `where(field, filter): Query` — convenience helper that creates a single-field `Query`
+
+## Building from source
+
+```bash
+bun install
+bun run build # zig build + tsc emit
+```
+
+The build step compiles the Zig binding for the current host and writes the `.node` artifact into `native/`, then emits the TypeScript declaration files to `dist/`.
+
+## Running tests
+
+```bash
+bun test
+```
+
+The test suite exercises insertion, querying, indexing, transforms, replication, and BSON round-trips using Bun’s test runner.
+
+## License
+
+MIT. See the accompanying `LICENSE` file (or the upstream [Albedo](https://github.com/klirix/albedo) repository) for details.

package/dist/index.d.ts

@@ -19,7 +19,7 @@ interface ObjectIdInstance {
 }
 interface ObjectIdConstructor {
     new (buffer?: ByteBuffer): ObjectIdInstance;
-    fromString(hex: string): ObjectIdInstance;
+    fromString(str: string): ObjectIdInstance;
 }
 interface AlbedoModule {
     ObjectId: ObjectIdConstructor;
@@ -48,18 +48,273 @@ export declare const BSON: {
     serialize: (value: unknown) => Uint8Array;
     deserialize: <T = unknown>(data: ByteBuffer) => T;
 };
+/**
+ * Native ObjectId class constructor.
+ *
+ * @example
+ * ```ts
+ * const id = new ObjectId();
+ * const parsed = ObjectId.fromString(id.toString());
+ * ```
+ */
+export declare const ObjectId: ObjectIdConstructor;
+/**
+ * Wrapper around a native Albedo bucket handle providing
+ * methods for CRUD operations, indexing, iteration, and
+ * replication support.
+ *
+ * @example
+ * ```ts
+ * import albedo, { Bucket, BSON } from 'albedo-node';
+ *
+ * const bucket = Bucket.open('data.db');
+ * bucket.insert({ name: 'Alice' });
+ *
+ * for (const doc of bucket.list({ query: { name: { $eq: 'Alice' } } })) {
+ *   console.log(doc);
+ * }
+ *
+ * bucket.close();
+ * ```
+ */
 export declare class Bucket {
     private handle;
+    /**
+     * Create a Bucket instance from an existing native handle.
+     * @param handle - opaque bucket handle returned by `albedo.open`
+     * @example
+     * ```ts
+     * const raw = albedo.open('foo.db');
+     * const bucket = new Bucket(raw);
+     * ```
+     */
     constructor(handle: object);
+    /**
+     * Open a bucket located at the given filesystem path.
+     * @param path - path to the bucket file
+     * @returns a new `Bucket` instance
+     * @example
+     * ```ts
+     * const bucket = Bucket.open('data.db');
+     * ```
+     */
     static open(path: string): Bucket;
+    /**
+     * Close the bucket and release native resources.
+     * @example
+     * ```ts
+     * bucket.close();
+     * ```
+     */
     close(): void;
+    /**
+     * Insert a document or raw byte buffer into the bucket.
+     * @param doc - object to serialize or pre-serialized buffer
+     * @example
+     * ```ts
+     * bucket.insert({ name: 'Bob' });
+     * ```
+     */
     insert(doc: object | ByteBuffer): void;
-    delete(query: object): void;
+    /**
+     * Delete documents matching the query. If no query is provided,
+     * all documents will be removed.
+     * @param query - filter object or `Query` instance
+     * @example
+     * ```ts
+     * bucket.delete({ name: { $eq: 'Bob' } });
+     * // or using Query builder
+     * bucket.delete(new Query().where('name', { $eq: 'Bob' }));
+     * ```
+     */
+    delete(query?: object | Query): void;
+    /**
+     * Retrieve information about all indexes defined on the bucket.
+     * @example
+     * ```ts
+     * console.log(bucket.indexes);
+     * ```
+     */
     get indexes(): Record<string, IndexInfo>;
+    /**
+     * Create or update an index on a field.
+     * @param name - index name (field path)
+     * @param options - index configuration
+     * @example
+     * ```ts
+     * bucket.ensureIndex('name', { unique: false, sparse: false, reverse: false });
+     * ```
+     */
     ensureIndex(name: string, options: IndexOptions): void;
+    /**
+     * Remove an index by name.
+     * @example
+     * ```ts
+     * bucket.dropIndex('name');
+     * ```
+     */
     dropIndex(name: string): void;
-    list<T>(query: object): Generator<T>;
-    transformIterator<T>(query: object): Generator<T, undefined, null | object>;
+    /**
+     * Iterate over documents matching the optional query.
+     * @param query - filter or `Query` object
+     * @yields each document deserialized from the bucket
+     * @example
+     * ```ts
+     * for (const doc of bucket.list({ query: { age: { $gt: 30 } } })) {
+     *   console.log(doc);
+     * }
+     * ```
+     */
+    list<T>(query?: object | Query): Generator<T>;
+    /**
+     * Normalize a query argument to a plain object, unpacking
+     * `Query` instances.
+     * @example
+     * ```ts
+     * Bucket.convertToQuery(new Query().where('x', { $eq: 1 }));
+     * Bucket.convertToQuery({ foo: { $exists: true } });
+     * ```
+     */
+    static convertToQuery(query?: object | Query): object;
+    /**
+     * Generator that allows reading and optionally modifying each
+     * document matching the query.
+     * @param query - filter or `Query` instance
+     * @yields the current document; the caller may send back an updated
+     * document or `null` to delete it.
+     * @example
+     * ```ts
+     * for (const doc of bucket.transformIterator({ query: { count: { $lt: 5 } } })) {
+     *   if (doc.count < 2) {
+     *     // update in-place
+     *     yield { ...doc, count: doc.count + 1 };
+     *   }
+     * }
+     * ```
+     */
+    transformIterator<T>(query?: object | Query): Generator<T, undefined, null | object>;
+    /**
+     * Apply a transformation function to each document matching the
+     * provided query. The predicate receives the current document and
+     * should return the modified document, or `null` to remove it.
+     *
+     * This is a helper built on top of `transformIterator` and mirrors its
+     * behavior but uses a simple callback API instead of a generator.
+     *
+     * @param query - filter or `Query` object
+     * @param fn - transformation function
+     * @example
+     * ```ts
+     * bucket.transform(where('active', { $eq: true }), doc => {
+     *   if (doc.count > 10) return null; // delete
+     *   return { ...doc, count: doc.count + 1 };
+     * });
+     * ```
+     */
+    transform<T extends object>(query: object | Query | undefined, fn: (doc: T) => T | null): 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);
+     * });
+     * ```
+     */
     setReplicationCallback(callback: (data: Uint8Array) => void): void;
+    /**
+     * Apply a batch of replication operations to this bucket.
+     * @param data - bytes produced by another bucket's replication
+     * @example
+     * ```ts
+     * bucket.applyReplicationBatch(remoteBytes);
+     * ```
+     */
     applyReplicationBatch(data: Uint8Array): void;
 }
+type BSONValue = any;
+type FilterOperators = {
+    $eq: BSONValue;
+} | {
+    $ne: BSONValue;
+} | {
+    $lt: BSONValue;
+} | {
+    $lte: BSONValue;
+} | {
+    $gt: BSONValue;
+} | {
+    $gte: BSONValue;
+} | {
+    $in: BSONValue[];
+} | {
+    $between: [BSONValue, BSONValue];
+} | {
+    $startsWith: string;
+} | {
+    $endsWith: string;
+} | {
+    $exists: boolean;
+} | {
+    $notExists: boolean;
+};
+/**
+ * Builder for query objects that can be used with bucket
+ * operations like `list`, `delete`, and `transform`.
+ *
+ * The class supports chaining to construct filters, sorting,
+ * and pagination (offset/limit).
+ */
+export declare class Query {
+    private _query;
+    /**
+     * Return the raw query object to pass to the native layer.
+     */
+    get query(): object;
+    /**
+     * Add a filter condition for the specified field.
+     * @param field - dot-separated path to the document field
+     * @param filter - comparison operator object
+     * @returns the same `Query` for chaining
+     * @example
+     * ```ts
+     * const q = new Query().where('age', { $gt: 18 });
+     * ```
+     */
+    where(field: string, filter: FilterOperators): this;
+    /**
+     * Specify sorting for the result set.
+     * @param field - field to sort by
+     * @param direction - `asc` or `desc` (defaults to `asc`)
+     * @example
+     * ```ts
+     * const q = new Query().sortBy('name', 'desc');
+     * ```
+     */
+    sortBy(field: string, direction?: "asc" | "desc"): this;
+    /**
+     * Set an offset and limit for pagination.
+     * @param offset - number of documents to skip
+     * @param limit - maximum number of documents to return
+     * @example
+     * ```ts
+     * const q = new Query().sector(10, 5);
+     * ```
+     */
+    sector(offset?: number, limit?: number): this;
+}
+/**
+ * Shortcut helper that creates a new `Query` with a single
+ * `where` clause applied.
+ *
+ * @param field - field name to filter on
+ * @param filter - filter operator object
+ * @returns a `Query` instance ready to use
+ * @example
+ * ```ts
+ * bucket.list(where('age', { $lt: 30 }));
+ * ```
+ */
+export declare function where(field: string, filter: FilterOperators): Query;

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Bucket = exports.BSON = void 0;
+exports.Query = exports.Bucket = exports.ObjectId = exports.BSON = void 0;
+exports.where = where;
 const platformSuffix = process.platform == "darwin" ? "macos" : process.platform === "win32" ? "windows" : process.platform;
 const archSuffix = process.arch === "x64" ? "x86_64" : process.arch === "arm64" ? "aarch64" : process.arch;
 const isMusl = process.versions.libc && process.versions.libc.includes("musl");
@@ -11,35 +12,142 @@ exports.BSON = {
     serialize: albedo.serialize,
     deserialize: albedo.deserialize,
 };
+/**
+ * Native ObjectId class constructor.
+ *
+ * @example
+ * ```ts
+ * const id = new ObjectId();
+ * const parsed = ObjectId.fromString(id.toString());
+ * ```
+ */
+exports.ObjectId = albedo.ObjectId;
+/**
+ * Wrapper around a native Albedo bucket handle providing
+ * methods for CRUD operations, indexing, iteration, and
+ * replication support.
+ *
+ * @example
+ * ```ts
+ * import albedo, { Bucket, BSON } from 'albedo-node';
+ *
+ * const bucket = Bucket.open('data.db');
+ * bucket.insert({ name: 'Alice' });
+ *
+ * for (const doc of bucket.list({ query: { name: { $eq: 'Alice' } } })) {
+ *   console.log(doc);
+ * }
+ *
+ * bucket.close();
+ * ```
+ */
 class Bucket {
     handle;
+    /**
+     * Create a Bucket instance from an existing native handle.
+     * @param handle - opaque bucket handle returned by `albedo.open`
+     * @example
+     * ```ts
+     * const raw = albedo.open('foo.db');
+     * const bucket = new Bucket(raw);
+     * ```
+     */
     constructor(handle) {
         this.handle = handle;
     }
+    /**
+     * Open a bucket located at the given filesystem path.
+     * @param path - path to the bucket file
+     * @returns a new `Bucket` instance
+     * @example
+     * ```ts
+     * const bucket = Bucket.open('data.db');
+     * ```
+     */
     static open(path) {
         const handle = albedo.open(path);
         return new Bucket(handle);
     }
+    /**
+     * Close the bucket and release native resources.
+     * @example
+     * ```ts
+     * bucket.close();
+     * ```
+     */
     close() {
         albedo.close(this.handle);
     }
+    /**
+     * Insert a document or raw byte buffer into the bucket.
+     * @param doc - object to serialize or pre-serialized buffer
+     * @example
+     * ```ts
+     * bucket.insert({ name: 'Bob' });
+     * ```
+     */
     insert(doc) {
         albedo.insert(this.handle, doc);
     }
+    /**
+     * Delete documents matching the query. If no query is provided,
+     * all documents will be removed.
+     * @param query - filter object or `Query` instance
+     * @example
+     * ```ts
+     * bucket.delete({ name: { $eq: 'Bob' } });
+     * // or using Query builder
+     * bucket.delete(new Query().where('name', { $eq: 'Bob' }));
+     * ```
+     */
     delete(query) {
-        albedo.delete(this.handle, query);
+        albedo.delete(this.handle, Bucket.convertToQuery(query));
     }
+    /**
+     * Retrieve information about all indexes defined on the bucket.
+     * @example
+     * ```ts
+     * console.log(bucket.indexes);
+     * ```
+     */
     get indexes() {
         return albedo.listIndexes(this.handle);
     }
+    /**
+     * Create or update an index on a field.
+     * @param name - index name (field path)
+     * @param options - index configuration
+     * @example
+     * ```ts
+     * bucket.ensureIndex('name', { unique: false, sparse: false, reverse: false });
+     * ```
+     */
     ensureIndex(name, options) {
         albedo.ensureIndex(this.handle, name, options);
     }
+    /**
+     * Remove an index by name.
+     * @example
+     * ```ts
+     * bucket.dropIndex('name');
+     * ```
+     */
     dropIndex(name) {
         albedo.dropIndex(this.handle, name);
     }
+    /**
+     * Iterate over documents matching the optional query.
+     * @param query - filter or `Query` object
+     * @yields each document deserialized from the bucket
+     * @example
+     * ```ts
+     * for (const doc of bucket.list({ query: { age: { $gt: 30 } } })) {
+     *   console.log(doc);
+     * }
+     * ```
+     */
     *list(query) {
-        const cursor = albedo.list(this.handle, query);
+        const cursor = albedo.list(this.handle, Bucket.convertToQuery(query));
         try {
             let data;
             while ((data = albedo.listData(cursor)) !== null) {
@@ -50,11 +158,43 @@ class Bucket {
             albedo.listClose(cursor);
         }
     }
+    /**
+     * Normalize a query argument to a plain object, unpacking
+     * `Query` instances.
+     * @example
+     * ```ts
+     * Bucket.convertToQuery(new Query().where('x', { $eq: 1 }));
+     * Bucket.convertToQuery({ foo: { $exists: true } });
+     * ```
+     */
+    static convertToQuery(query) {
+        if (query instanceof Query) {
+            return query.query;
+        }
+        return query || {};
+    }
+    /**
+     * Generator that allows reading and optionally modifying each
+     * document matching the query.
+     * @param query - filter or `Query` instance
+     * @yields the current document; the caller may send back an updated
+     * document or `null` to delete it.
+     * @example
+     * ```ts
+     * for (const doc of bucket.transformIterator({ query: { count: { $lt: 5 } } })) {
+     *   if (doc.count < 2) {
+     *     // update in-place
+     *     yield { ...doc, count: doc.count + 1 };
+     *   }
+     * }
+     * ```
+     */
     *transformIterator(query) {
-        const iter = albedo.transform(this.handle, query);
+        const queryObj = Bucket.convertToQuery(query);
+        const iter = albedo.transform(this.handle, queryObj);
         try {
             let data;
-            while ((data = albedo.transformData(iter)) !== null) {
+            while ((data = albedo.transformData(iter)) !== undefined) {
                 const newDoc = yield data;
                 albedo.transformApply(iter, newDoc);
             }
@@ -63,11 +203,136 @@ class Bucket {
             albedo.transformClose(iter);
         }
     }
+    /**
+     * Apply a transformation function to each document matching the
+     * provided query. The predicate receives the current document and
+     * should return the modified document, or `null` to remove it.
+     *
+     * This is a helper built on top of `transformIterator` and mirrors its
+     * behavior but uses a simple callback API instead of a generator.
+     *
+     * @param query - filter or `Query` object
+     * @param fn - transformation function
+     * @example
+     * ```ts
+     * bucket.transform(where('active', { $eq: true }), doc => {
+     *   if (doc.count > 10) return null; // delete
+     *   return { ...doc, count: doc.count + 1 };
+     * });
+     * ```
+     */
+    transform(query, fn) {
+        const queryObj = Bucket.convertToQuery(query);
+        const iter = albedo.transform(this.handle, queryObj);
+        try {
+            let data;
+            while ((data = albedo.transformData(iter)) !== undefined) {
+                albedo.transformApply(iter, fn(data));
+            }
+        }
+        finally {
+            albedo.transformClose(iter);
+        }
+    }
+    /**
+     * 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);
+     * });
+     * ```
+     */
     setReplicationCallback(callback) {
         albedo.setReplicationCallback(this.handle, callback);
     }
+    /**
+     * Apply a batch of replication operations to this bucket.
+     * @param data - bytes produced by another bucket's replication
+     * @example
+     * ```ts
+     * bucket.applyReplicationBatch(remoteBytes);
+     * ```
+     */
     applyReplicationBatch(data) {
         albedo.applyReplicationBatch(this.handle, data);
     }
 }
 exports.Bucket = Bucket;
+/**
+ * Builder for query objects that can be used with bucket
+ * operations like `list`, `delete`, and `transform`.
+ *
+ * The class supports chaining to construct filters, sorting,
+ * and pagination (offset/limit).
+ */
+class Query {
+    _query = {};
+    /**
+     * Return the raw query object to pass to the native layer.
+     */
+    get query() {
+        return this._query;
+    }
+    /**
+     * Add a filter condition for the specified field.
+     * @param field - dot-separated path to the document field
+     * @param filter - comparison operator object
+     * @returns the same `Query` for chaining
+     * @example
+     * ```ts
+     * const q = new Query().where('age', { $gt: 18 });
+     * ```
+     */
+    where(field, filter) {
+        if (!this._query.query) {
+            this._query.query = {};
+        }
+        this._query.query[field] = filter;
+        return this;
+    }
+    /**
+     * Specify sorting for the result set.
+     * @param field - field to sort by
+     * @param direction - `asc` or `desc` (defaults to `asc`)
+     * @example
+     * ```ts
+     * const q = new Query().sortBy('name', 'desc');
+     * ```
+     */
+    sortBy(field, direction = "asc") {
+        this._query.sort = direction === "asc" ? { asc: field } : { desc: field };
+        return this;
+    }
+    /**
+     * Set an offset and limit for pagination.
+     * @param offset - number of documents to skip
+     * @param limit - maximum number of documents to return
+     * @example
+     * ```ts
+     * const q = new Query().sector(10, 5);
+     * ```
+     */
+    sector(offset, limit) {
+        this._query.sector = { offset, limit };
+        return this;
+    }
+}
+exports.Query = Query;
+/**
+ * Shortcut helper that creates a new `Query` with a single
+ * `where` clause applied.
+ *
+ * @param field - field name to filter on
+ * @param filter - filter operator object
+ * @returns a `Query` instance ready to use
+ * @example
+ * ```ts
+ * bucket.list(where('age', { $lt: 30 }));
+ * ```
+ */
+function where(field, filter) {
+    return new Query().where(field, filter);
+}

package/example/index.js

@@ -1,4 +1,4 @@
-import { BSON, Bucket } from "albedo-node";
+import { BSON, Bucket, where } from "albedo-node";
 import Database from "bun:sqlite";
 import { unlinkSync } from "fs";
 
@@ -81,10 +81,7 @@ console.time("Query index x 100");
 for (let i = 0; i < 100; i++) {
   
   bucket
-    .list({
-      query: { _id: Math.floor(Math.random() * docNum) },
-      sector: { limit: 100 },
-    })
+    .list(where("_id", { $eq: Math.floor(Math.random() * docNum) }).sector(0, 100))
     .next();
 }
 console.timeEnd("Query index x 100");

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "albedo-node",
-  "version": "0.5.4",
-  "description": "Albedo DB native bindings",
+  "version": "0.5.6",
+  "description": "High-performance embedded database for Node.js with native bindings, BSON support, indexing, and replication",
+  "keywords": [
+    "albedo",
+    "database",
+    "embedded-database",
+    "bson",
+    "native",
+    "node-addon"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/klirix/albedo-node.git"
+  },
+  "homepage": "https://github.com/klirix/albedo-node#readme",
+  "bugs": {
+    "url": "https://github.com/klirix/albedo-node/issues"
+  },
   "scripts": {
     "build:binding": "zig build",
     "build:ts": "bun run tsc -p tsconfig.json",