albedo-node 0.5.3

package/bun.lock

@@ -0,0 +1,19 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "albedo-node",
+      "devDependencies": {
+        "@types/node": "^24.0.0",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/node@24.10.13", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-oH72nZRfDv9lADUBSo104Aq7gPHpQZc4BTx38r9xf9pg5LfP6EzSyH2n7qFmmxRQXh7YlUXODcYsg6PuTDSxGg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+type ByteBuffer = Uint8Array;
+type BucketHandle = object;
+type ListIteratorHandle = object;
+type TransformIteratorHandle = 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;
+}
+interface ObjectIdConstructor {
+    new (buffer?: ByteBuffer): ObjectIdInstance;
+    fromString(hex: string): ObjectIdInstance;
+}
+interface AlbedoModule {
+    ObjectId: ObjectIdConstructor;
+    serialize(value: unknown): Uint8Array;
+    deserialize<T = unknown>(data: ByteBuffer): T;
+    open(path: string): 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;
+    setReplicationCallback(bucket: BucketHandle, callback: (data: Uint8Array) => void): void;
+    applyReplicationBatch(bucket: BucketHandle, data: ByteBuffer): void;
+}
+declare const albedo: AlbedoModule;
+export default albedo;
+export declare const BSON: {
+    serialize: (value: unknown) => Uint8Array;
+    deserialize: <T = unknown>(data: ByteBuffer) => T;
+};
+export declare class Bucket {
+    private handle;
+    constructor(handle: object);
+    static open(path: string): Bucket;
+    close(): void;
+    insert(doc: object | ByteBuffer): void;
+    get indexes(): Record<string, IndexInfo>;
+    ensureIndex(name: string, options: IndexOptions): void;
+    dropIndex(name: string): void;
+    list<T>(query: object): Generator<T>;
+    transformIterator<T>(query: object): Generator<T, undefined, null | object>;
+    setReplicationCallback(callback: (data: Uint8Array) => void): void;
+    applyReplicationBatch(data: Uint8Array): void;
+}

package/dist/index.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bucket = exports.BSON = void 0;
+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");
+const libcSuffix = isMusl ? "_musl" : "";
+const albedo = require(`../native/albedo.${archSuffix}_${platformSuffix}${libcSuffix}.node`);
+exports.default = albedo;
+exports.BSON = {
+    serialize: albedo.serialize,
+    deserialize: albedo.deserialize,
+};
+class Bucket {
+    handle;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    static open(path) {
+        const handle = albedo.open(path);
+        return new Bucket(handle);
+    }
+    close() {
+        albedo.close(this.handle);
+    }
+    insert(doc) {
+        albedo.insert(this.handle, doc);
+    }
+    get indexes() {
+        return albedo.listIndexes(this.handle);
+    }
+    ensureIndex(name, options) {
+        albedo.ensureIndex(this.handle, name, options);
+    }
+    dropIndex(name) {
+        albedo.dropIndex(this.handle, name);
+    }
+    *list(query) {
+        const cursor = albedo.list(this.handle, query);
+        try {
+            let data;
+            while ((data = albedo.listData(cursor)) !== null) {
+                yield data;
+            }
+        }
+        finally {
+            albedo.listClose(cursor);
+        }
+    }
+    *transformIterator(query) {
+        const iter = albedo.transform(this.handle, query);
+        try {
+            let data;
+            while ((data = albedo.transformData(iter)) !== null) {
+                const newDoc = yield data;
+                albedo.transformApply(iter, newDoc);
+            }
+        }
+        finally {
+            albedo.transformClose(iter);
+        }
+    }
+    setReplicationCallback(callback) {
+        albedo.setReplicationCallback(this.handle, callback);
+    }
+    applyReplicationBatch(data) {
+        albedo.applyReplicationBatch(this.handle, data);
+    }
+}
+exports.Bucket = Bucket;

package/example/README.md

@@ -0,0 +1,15 @@
+# example
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.1. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/example/bun.lock

@@ -0,0 +1,108 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "example",
+      "dependencies": {
+        "albedo-node": "../",
+        "better-sqlite3": "^12.6.2",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@24.10.13", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-oH72nZRfDv9lADUBSo104Aq7gPHpQZc4BTx38r9xf9pg5LfP6EzSyH2n7qFmmxRQXh7YlUXODcYsg6PuTDSxGg=="],
+
+    "albedo-node": ["albedo-node@file:..", { "devDependencies": { "@types/node": "^24.0.0", "typescript": "^5.9.3" } }],
+
+    "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
+
+    "better-sqlite3": ["better-sqlite3@12.6.2", "", { "dependencies": { "bindings": "^1.5.0", "prebuild-install": "^7.1.1" } }, "sha512-8VYKM3MjCa9WcaSAI3hzwhmyHVlH8tiGFwf0RlTsZPWJ1I5MkzjiudCo4KC4DxOaL/53A5B1sI/IbldNFDbsKA=="],
+
+    "bindings": ["bindings@1.5.0", "", { "dependencies": { "file-uri-to-path": "1.0.0" } }, "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ=="],
+
+    "bl": ["bl@4.1.0", "", { "dependencies": { "buffer": "^5.5.0", "inherits": "^2.0.4", "readable-stream": "^3.4.0" } }, "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w=="],
+
+    "buffer": ["buffer@5.7.1", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.1.13" } }, "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "chownr": ["chownr@1.1.4", "", {}, "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg=="],
+
+    "decompress-response": ["decompress-response@6.0.0", "", { "dependencies": { "mimic-response": "^3.1.0" } }, "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ=="],
+
+    "deep-extend": ["deep-extend@0.6.0", "", {}, "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA=="],
+
+    "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
+
+    "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
+
+    "expand-template": ["expand-template@2.0.3", "", {}, "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg=="],
+
+    "file-uri-to-path": ["file-uri-to-path@1.0.0", "", {}, "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw=="],
+
+    "fs-constants": ["fs-constants@1.0.0", "", {}, "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow=="],
+
+    "github-from-package": ["github-from-package@0.0.0", "", {}, "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw=="],
+
+    "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
+
+    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
+
+    "ini": ["ini@1.3.8", "", {}, "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew=="],
+
+    "mimic-response": ["mimic-response@3.1.0", "", {}, "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ=="],
+
+    "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
+
+    "mkdirp-classic": ["mkdirp-classic@0.5.3", "", {}, "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A=="],
+
+    "napi-build-utils": ["napi-build-utils@2.0.0", "", {}, "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA=="],
+
+    "node-abi": ["node-abi@3.87.0", "", { "dependencies": { "semver": "^7.3.5" } }, "sha512-+CGM1L1CgmtheLcBuleyYOn7NWPVu0s0EJH2C4puxgEZb9h8QpR9G2dBfZJOAUhi7VQxuBPMd0hiISWcTyiYyQ=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "prebuild-install": ["prebuild-install@7.1.3", "", { "dependencies": { "detect-libc": "^2.0.0", "expand-template": "^2.0.3", "github-from-package": "0.0.0", "minimist": "^1.2.3", "mkdirp-classic": "^0.5.3", "napi-build-utils": "^2.0.0", "node-abi": "^3.3.0", "pump": "^3.0.0", "rc": "^1.2.7", "simple-get": "^4.0.0", "tar-fs": "^2.0.0", "tunnel-agent": "^0.6.0" }, "bin": { "prebuild-install": "bin.js" } }, "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug=="],
+
+    "pump": ["pump@3.0.3", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA=="],
+
+    "rc": ["rc@1.2.8", "", { "dependencies": { "deep-extend": "^0.6.0", "ini": "~1.3.0", "minimist": "^1.2.0", "strip-json-comments": "~2.0.1" }, "bin": { "rc": "./cli.js" } }, "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw=="],
+
+    "readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
+
+    "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
+
+    "semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+
+    "simple-concat": ["simple-concat@1.0.1", "", {}, "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q=="],
+
+    "simple-get": ["simple-get@4.0.1", "", { "dependencies": { "decompress-response": "^6.0.0", "once": "^1.3.1", "simple-concat": "^1.0.0" } }, "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA=="],
+
+    "string_decoder": ["string_decoder@1.3.0", "", { "dependencies": { "safe-buffer": "~5.2.0" } }, "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA=="],
+
+    "strip-json-comments": ["strip-json-comments@2.0.1", "", {}, "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ=="],
+
+    "tar-fs": ["tar-fs@2.1.4", "", { "dependencies": { "chownr": "^1.1.1", "mkdirp-classic": "^0.5.2", "pump": "^3.0.0", "tar-stream": "^2.1.4" } }, "sha512-mDAjwmZdh7LTT6pNleZ05Yt65HC3E+NiQzl672vQG38jIrehtJk/J3mNwIg+vShQPcLF/LV7CMnDW6vjj6sfYQ=="],
+
+    "tar-stream": ["tar-stream@2.2.0", "", { "dependencies": { "bl": "^4.0.3", "end-of-stream": "^1.4.1", "fs-constants": "^1.0.0", "inherits": "^2.0.3", "readable-stream": "^3.1.1" } }, "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ=="],
+
+    "tunnel-agent": ["tunnel-agent@0.6.0", "", { "dependencies": { "safe-buffer": "^5.0.1" } }, "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="],
+
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+  }
+}

package/example/index.js

@@ -0,0 +1,95 @@
+import { BSON, Bucket } from "albedo-node";
+import Database from "bun:sqlite";
+import { unlinkSync } from "fs";
+
+const docNum = 100000;
+
+const sqliteDb = new Database("db.sqlite");
+sqliteDb
+  .prepare(
+    `
+  CREATE TABLE IF NOT EXISTS documents (
+    _id INTEGER PRIMARY KEY,
+    doc JSON
+  );
+`,
+  )
+  .run();
+
+sqliteDb.prepare("drop index IF EXISTS idx_doc_id;").run();
+sqliteDb.prepare("create unique index idx_doc_id on documents(json_extract(doc, '$._id'));").run();
+
+console.time("Insert 100000 documents into SQLite");
+const insertStmt = sqliteDb.prepare("INSERT INTO documents (doc) VALUES (json(?))");
+for (let i = 0; i < docNum; i++) {
+    insertStmt.run(JSON.stringify({
+      _id: i,
+      name: `Name ${i}`,
+      age: i,
+    }));
+}
+console.timeEnd("Insert 100000 documents into SQLite");
+
+console.time("Query scan x 100 in SQLite");
+for (let i = 0; i < 100; i++) {
+  const row = sqliteDb
+    .prepare("SELECT doc FROM documents WHERE json_extract(doc, '$.age') = ? LIMIT 100")
+    .get(Math.floor(Math.random() * docNum));
+  if (row) JSON.parse(row.doc);
+}
+console.timeEnd("Query scan x 100 in SQLite");
+
+console.time("Query index x 100 in SQLite");
+for (let i = 0; i < 100; i++) {
+  const row = sqliteDb
+    .prepare(
+      "SELECT doc FROM documents WHERE json_extract(doc, '$._id') = ? LIMIT 100",
+    )
+    .get(Math.floor(Math.random() * docNum));
+  if (row) JSON.parse(row.doc);
+}
+console.timeEnd("Query index x 100 in SQLite");
+
+sqliteDb.close();
+
+const bucket = Bucket.open("db.bucket");
+
+// bucket.dropIndex("_id");
+
+console.time("Insert 100000 documents");
+for (let i = 0; i < docNum; i++) {
+  bucket.insert({
+    _id: i,
+    name: `Name ${i}`,
+    age: i,
+  });
+}
+console.timeEnd("Insert 100000 documents");
+
+console.time("Query scan x 100");
+for (let i = 0; i < 100; i++) {
+  bucket
+    .list({
+      query: { age: Math.floor(Math.random() * docNum) },
+      sector: { limit: 100 },
+    })
+    .next();
+}
+console.timeEnd("Query scan x 100");
+
+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 },
+    })
+    .next();
+}
+console.timeEnd("Query index x 100");
+
+bucket.close();
+
+unlinkSync("db.sqlite");
+unlinkSync("db.bucket");

package/example/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "example",
+  "module": "index.ts",
+  "type": "module",
+  "private": true,
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "albedo-node": "../",
+    "better-sqlite3": "^12.6.2"
+  }
+}

package/example/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "albedo-node",
+  "version": "0.5.3",
+  "description": "Albedo DB native bindings",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build:binding": "zig build",
+    "build:ts": "bun run tsc -p tsconfig.json",
+    "build": "bun run build:binding && bun run build:ts",
+    "release": "bun ./scripts/publish.ts"
+  },
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/publish.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { $ } from "bun";
+
+const dry = process.argv.includes("--dry-run");
+
+async function main() {
+  const root = process.cwd();
+  const pkgPath = path.join(root, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+
+  const name = pkg.name || "(unknown)";
+  const version = pkg.version || "0.0.0";
+
+  console.log(`🔧 Building ${name}@${version}...`);
+  const buildRes = await $`bun run build`;
+  if (buildRes.exitCode !== 0) throw new Error("build failed");
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), `${name.replace("/", "-")}-`));
+  console.log(`📦 Preparing publish directory: ${tmp}`);
+
+  function copyOrFail(rel: string) {
+    const src = path.join(root, rel);
+    if (!fs.existsSync(src)) throw new Error(`Required path not found: ${rel}`);
+    fs.cpSync(src, path.join(tmp, rel), { recursive: true });
+  }
+
+  // required distributables
+  copyOrFail("dist");
+  copyOrFail("native");
+
+  // copy docs if present
+  ["README.md", "LICENSE", "CHANGELOG.md"].forEach((f) => {
+    const p = path.join(root, f);
+    if (fs.existsSync(p)) fs.copyFileSync(p, path.join(tmp, f));
+  });
+
+  // sanitize package.json for publish (remove dev-only fields & scripts)
+  const publishPkg = { ...pkg } as Record<string, any>;
+  delete publishPkg.devDependencies;
+  delete publishPkg.scripts;
+  publishPkg.files = Array.from(new Set([...(publishPkg.files || []), "dist", "native"]));
+  if (publishPkg.private) delete publishPkg.private;
+
+  fs.writeFileSync(path.join(tmp, "package.json"), JSON.stringify(publishPkg, null, 2) + "\n");
+
+  console.log("📋 Files staged for publish:");
+  const lsRes = await $`ls -1`.cwd(tmp);
+  if (lsRes.exitCode === 0) console.log(String(lsRes.stdout || "").trim());
+
+  if (dry) {
+    console.log("⚠️ Dry run — skipping npm publish. Use --no-dry-run to actually publish.");
+  } else {
+    const packOnly = process.argv.includes("--pack-only");
+
+    console.log("➡️ Creating package tarball with `bun pm pack`...");
+    const packRes = await $`bun pm pack --quiet`.cwd(tmp);
+    if (packRes.exitCode !== 0) {
+      console.error(String(packRes.stderr || packRes.stdout || ""));
+      throw new Error(`bun pm pack failed (${packRes.exitCode})`);
+    }
+    console.log("✅ Package tarball created:", packRes.stdout.toString('utf8'));
+
+    const tarballName = String(packRes.stdout || packRes.stderr || "").trim().split(/\r?\n/).pop();
+    const tarballPath = path.join(tmp, tarballName || "package.tgz");
+    console.log(`📦 Packaged: ${tarballPath}`);
+
+    if (packOnly) {
+      console.log("ℹ️ --pack-only provided; skipping publish.");
+    } else {
+      console.log("➡️ Publishing tarball with bun publish...");
+      const publishRes = await $`npm publishbun --access public ${tarballPath}`.cwd(root);
+      if (publishRes.exitCode !== 0) {
+        console.error(String(publishRes.stderr || publishRes.stdout || ""));
+        throw new Error(`bun publish failed (${publishRes.exitCode})`);
+      }
+      console.log("✅ Publish complete.");
+    }
+  }
+
+  fs.rmSync(tmp, { recursive: true, force: true });
+  console.log(`🎉 ${name}@${version} ${dry ? "(dry-run)" : "published"}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/index.ts"]
+}