nodblite 0.0.0-stage → 0.6.7

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Titor-Z
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# nodblite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**像 SQLite 一样小巧的单文件 NoSQL 文档数据库** —— MongoDB 风格查询,零配置,无需服务进程。
+
+```bash
+npm install nodblite
+```
+
+```js
+import { Database } from 'nodblite';
+
+const db = new Database('app.nodb');
+
+const id = db.insert('users', { name: '张三', age: 30 });
+const adults = db.find('users', { age: { $gte: 18 } }, { sort: { age: -1 } });
+
+db.close();
+```
+
+整个数据库就是一个 `.nodb` 文件 —— 复制即迁移,备份即拷贝。
+
+📖 **[完整文档](https://titor-z.github.io/nosqlite/)** · [与 MongoDB 的差异](https://titor-z.github.io/nosqlite/reference/compatibility/)
+
+---
+
+## 为什么用它
+
+| | |
+|---|---|
+| **零配置** | 没有服务进程,没有端口,没有配置文件 |
+| **单文件** | 一个 `.nodb` 文件,`cp` 就是备份 |
+| **MongoDB 语义** | 查询/更新/索引语法与 MongoDB 一致,迁移成本低 |
+| **同步 API** | 没有 `await` 地狱,手感像 `better-sqlite3` |
+| **TypeScript** | 完整类型定义,`find<T>()` 泛型推断 |
+
+## 安装
+
+```bash
+npm install nodblite
+```
+
+需要 Node.js 18+。底层通过 [koffi](https://www.npmjs.com/package/koffi) 调用预编译动态库,**不需要 node-gyp、不需要 Python、不需要 C++ 编译器**。
+
+支持平台:macOS(arm64/x64)、Linux(x64)、Windows(x64)。
+
+## 快速上手
+
+```js
+import { Database } from 'nodblite';
+
+const db = new Database('app.nodb');   // 不存在则自动创建
+
+// 插入
+const id = db.insert('users', { name: '张三', age: 30 });
+db.insertMany('users', [
+  { name: '李四', age: 25 },
+  { name: '王五', age: 42 },
+]);
+
+// 查询
+const adults = db.find('users', { age: { $gte: 18 } }, { sort: { age: -1 } });
+const one = db.get('users', id);
+
+// 分页:一次拿到总数与当页,不用查两次
+const { total, items } = db.findPage('users', {}, { skip: 0, limit: 20 });
+
+// 更新
+db.update('users', { name: '张三' }, { $inc: { age: 1 } });
+db.upsert('users', { email: 'a@b.c' }, { $set: { name: '新人' } });
+
+// 删除
+db.delete('users', { age: { $lt: 18 } });
+
+db.close();
+```
+
+## 索引
+
+```js
+// 单字段
+db.createIndex('users', 'age_1', 'age');
+
+// 唯一
+db.createIndex('users', 'email_1', 'email', { unique: true });
+
+// 复合(遵循 MongoDB 前缀原则)
+db.createIndex('users', 'status_age', 'status', { fields: ['status', 'age'] });
+
+// 降序
+db.createIndex('users', 'age_-1', 'age', { fields: ['age'], directions: [-1] });
+
+// 看看查询会不会走索引
+const plan = db.explain('users', { age: { $gte: 18 } });
+console.log(plan.stage);      // 'IXSCAN' 或 'COLLSCAN'
+console.log(plan.indexName);  // 'age_1'
+```
+
+## TypeScript
+
+```ts
+import { Database } from 'nodblite';
+
+interface User {
+  _id?: string;
+  name: string;
+  age: number;
+  tags?: string[];
+}
+
+const db = new Database('app.nodb');
+
+const adults: User[] = db.find<User>('users', { age: { $gte: 18 } });
+const page = db.findPage<User>('users', { tags: { $all: ['admin'] } });
+```
+
+类型会拦截常见错误:
+
+```ts
+db.find<User>('users', { age: { $gte: '字符串' } });  // ❌ 类型错误
+db.update<User>('users', {}, { $inc: { age: 'x' } }); // ❌ 类型错误
+```
+
+## 支持的查询操作符
+
+`$eq` `$ne` `$gt` `$gte` `$lt` `$lte` `$in` `$nin` `$regex`
+`$exists` `$type` `$all` `$size` `$elemMatch`
+`$and` `$or` `$nor` `$not`
+
+## 支持的更新操作符
+
+`$set` `$unset` `$inc` `$mul` `$min` `$max` `$rename`
+`$push` `$addToSet` `$pull` `$pop` `$currentDate`
+
+## 资源管理
+
+```js
+// 手动关闭
+const db = new Database('app.nodb');
+db.close();
+
+// 或用 using 自动关闭(TypeScript 5.2+ / Node 22+)
+using db = new Database('app.nodb');
+```
+
+## 错误处理
+
+所有错误都是 `NodbliteError` 的子类,带稳定的 `code`:
+
+```js
+import { Errors } from 'nodblite';
+
+try {
+  db.insert('users', { email: 'a@b.c' });
+} catch (e) {
+  if (e instanceof Errors.DuplicateKeyError) {
+    console.log('邮箱已存在');
+  }
+}
+```
+
+| 错误类 | code | 场景 |
+|---|---|---|
+| `DuplicateKeyError` | 1 | 主键或唯一索引冲突 |
+| `InvalidPathError` | 2 | 后缀不是 `.nodb` |
+| `InvalidFilterError` | 6 | 过滤条件语法错误 |
+| `InvalidUpdateError` | 7 | 更新操作符错误 |
+| `InvalidDocumentError` | 10 | 文档不是合法 JSON 对象 |
+
+## 常见问题
+
+**能多进程同时写吗?**
+不能。`.nodb` 由进程独占(SQLite 同款约束)。需要多服务共享,请用 `nodblite-server` + MongoDB 驱动。
+
+**和 MongoDB driver 有什么区别?**
+这个包是**进程内直连**,没有网络开销,没有服务进程 —— 适合桌面应用、CLI、单机服务。需要跨进程/跨语言共享时用 wire 协议。
+
+**Deno / Bun 能用吗?**
+这个包依赖 koffi(Node 原生模块),目前只在 Node.js 上验证过。Deno/Bun 推荐用 wire 协议。
+
+**性能如何?**
+查询走索引时是高选择率快 300–4000 倍(10 万文档实测)。批量写入用 `insertMany`,比逐条快两个数量级。详见[性能文档](https://titor-z.github.io/nosqlite/reference/performance/)。
+
+## License
+
+Apache-2.0

package/dist/bindings.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 定位动态库。
+ *
+ * 查找顺序:
+ * 1. 环境变量 `NODBLITE_LIB`(显式指定,最高优先级)
+ * 2. 包内 `prebuilds/<platform>-<arch>/`
+ * 3. 包内 `prebuilds/`
+ * 4. 开发场景:`../target/release/` 与 `../target/debug/`
+ */
+export function resolveLibPath(): any;
+/** 加载 koffi 并声明所有用到的 C 函数与结构。 */
+export function loadBindings(libPath?: any): {
+    koffi: any;
+    Slice: any;
+    Result: any;
+    open: any;
+    close: any;
+    insert: any;
+    insertMany: any;
+    get: any;
+    update: any;
+    delete: any;
+    upsert: any;
+    count: any;
+    find: any;
+    findPage: any;
+    listCollections: any;
+    createIndex: any;
+    createIndexComposite: any;
+    listIndexes: any;
+    dropIndex: any;
+    explain: any;
+    cursorNext: any;
+    cursorClose: any;
+    resultFree: any;
+    lastError: any;
+    lastErrorCode: any;
+};
+/** 把 C 的 `NodbliteSlice` 解成 JS 字符串。 */
+export function sliceToString(koffi: any, s: any): any;

package/dist/bindings.js

@@ -0,0 +1,124 @@
+// nodblite 的 koffi 绑定层。
+//
+// 本文件只做「C ABI ↔ JS」的机械映射,不含业务逻辑。
+// 所有函数签名必须与 include/nodblite.h 严格一致 —— 改头文件后要同步这里。
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** 各平台动态库文件名。 */
+const LIB_NAMES = {
+    darwin: 'libnodblite.dylib',
+    linux: 'libnodblite.so',
+    win32: 'nodblite.dll',
+};
+/**
+ * 定位动态库。
+ *
+ * 查找顺序:
+ * 1. 环境变量 `NODBLITE_LIB`(显式指定,最高优先级)
+ * 2. 包内 `prebuilds/<platform>-<arch>/`
+ * 3. 包内 `prebuilds/`
+ * 4. 开发场景:`../target/release/` 与 `../target/debug/`
+ */
+export function resolveLibPath() {
+    if (process.env.NODBLITE_LIB) {
+        if (!existsSync(process.env.NODBLITE_LIB)) {
+            throw new Error(`NODBLITE_LIB 指向的文件不存在: ${process.env.NODBLITE_LIB}`);
+        }
+        return process.env.NODBLITE_LIB;
+    }
+    const name = LIB_NAMES[process.platform];
+    if (!name) {
+        throw new Error(`不支持的平台: ${process.platform}(支持 darwin / linux / win32)`);
+    }
+    const candidates = [
+        join(__dirname, '..', 'prebuilds', `${process.platform}-${process.arch}`, name),
+        join(__dirname, '..', 'prebuilds', name),
+        // 源码仓库内直接使用时
+        join(__dirname, '..', '..', 'target', 'release', name),
+        join(__dirname, '..', '..', 'target', 'debug', name),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    throw new Error(`找不到 nodblite 动态库(${name})。\n` +
+        `已尝试:\n${candidates.map((c) => `  - ${c}`).join('\n')}\n\n` +
+        `解决办法:\n` +
+        `  1. 在源码仓库执行 cargo build --release,或\n` +
+        `  2. 设置环境变量 NODBLITE_LIB=/path/to/${name}\n` +
+        `  3. 从 https://github.com/Titor-Z/nosqlite/releases 下载 FFI 包`);
+}
+// koffi 的结构类型注册表是**全局**的:`koffi.struct()` 同名只能调一次,
+// 否则抛 "Duplicate type name"。所以这里缓存起来,进程内只声明一次。
+let cachedKoffi = null;
+let cachedTypes = null;
+/** 拿到 koffi 与只声明一次的结构类型。 */
+function getKoffiAndTypes() {
+    if (cachedKoffi)
+        return { koffi: cachedKoffi, ...cachedTypes };
+    const koffi = require('koffi');
+    const Slice = koffi.struct('NodbliteSlice', {
+        ptr: 'uint8_t *',
+        len: 'size_t',
+    });
+    const Result = koffi.struct('NodbliteResult', {
+        code: 'int32',
+        count: 'uint64',
+        affected: 'uint64',
+        docs: koffi.pointer(Slice),
+        value: Slice,
+    });
+    cachedKoffi = koffi;
+    cachedTypes = { Slice, Result };
+    return { koffi, Slice, Result };
+}
+/** 加载 koffi 并声明所有用到的 C 函数与结构。 */
+export function loadBindings(libPath = resolveLibPath()) {
+    const { koffi, Slice, Result } = getKoffiAndTypes();
+    const lib = koffi.load(libPath);
+    // ---------- 函数 ----------
+    const fn = (sig) => lib.func(sig);
+    return {
+        koffi,
+        Slice,
+        Result,
+        open: fn('void *nodblite_open(const char *path, uint8_t create_if_missing)'),
+        close: fn('void nodblite_close(void *db)'),
+        insert: fn('void *nodblite_insert(void *db, const char *coll, const char *doc)'),
+        insertMany: fn('void *nodblite_insert_many(void *db, const char *coll, const char *docs)'),
+        get: fn('void *nodblite_get(void *db, const char *coll, const char *id)'),
+        update: fn('void *nodblite_update(void *db, const char *coll, const char *filter, const char *upd)'),
+        delete: fn('void *nodblite_delete(void *db, const char *coll, const char *filter)'),
+        upsert: fn('void *nodblite_upsert(void *db, const char *coll, const char *filter, const char *upd)'),
+        count: fn('void *nodblite_count(void *db, const char *coll, const char *filter)'),
+        find: fn('void *nodblite_find(void *db, const char *coll, const char *filter, ' +
+            'const char *sort, const char *fields, uint64_t skip, uint64_t limit)'),
+        findPage: fn('void *nodblite_find_page(void *db, const char *coll, const char *filter, ' +
+            'const char *sort, const char *fields, uint64_t skip, uint64_t limit, ' +
+            'uint8_t limit_is_null)'),
+        listCollections: fn('void *nodblite_list_collections(void *db)'),
+        createIndex: fn('void *nodblite_create_index(void *db, const char *coll, const char *name, ' +
+            'const char *field, uint8_t unique, uint8_t sparse)'),
+        createIndexComposite: fn('void *nodblite_create_index_composite(void *db, const char *coll, const char *name, ' +
+            'const char *fields, const char *dirs, uint8_t unique, uint8_t sparse)'),
+        listIndexes: fn('void *nodblite_list_indexes(void *db, const char *coll)'),
+        dropIndex: fn('void *nodblite_drop_index(void *db, const char *coll, const char *name)'),
+        explain: fn('void *nodblite_explain(void *db, const char *coll, const char *filter, ' +
+            'const char *sort)'),
+        cursorNext: fn('void *nodblite_cursor_next(void *cur)'),
+        cursorClose: fn('void nodblite_cursor_close(void *cur)'),
+        resultFree: fn('void nodblite_result_free(void *r)'),
+        lastError: fn('const char *nodblite_last_error()'),
+        lastErrorCode: fn('int32 nodblite_last_error_code()'),
+    };
+}
+/** 把 C 的 `NodbliteSlice` 解成 JS 字符串。 */
+export function sliceToString(koffi, s) {
+    if (!s || s.len === 0)
+        return '';
+    return Buffer.from(koffi.decode(s.ptr, 'uint8_t', s.len)).toString('utf8');
+}

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+/** 所有 nodblite 错误的基类。 */
+export class NodbliteError extends Error {
+    constructor(code: any, message: any, op: any);
+    name: any;
+    code: any;
+    /** 出错的操作名,如 "insert" / "find"。 */
+    op: any;
+}
+/** 动态创建具体错误类,便于 `instanceof` 判断。 */
+export const Errors: {
+    [k: string]: any;
+};
+/**
+ * 一个 nodblite 数据库。
+ *
+ * 用法与 better-sqlite3 类似:
+ * ```js
+ * import { Database } from 'nodblite';
+ * const db = new Database('app.nodb');
+ * db.collection('users').insert({ name: '张三' });
+ * db.close();
+ * ```
+ */
+export class Database {
+    /**
+     * @param {string} path 数据库文件路径(必须以 `.nodb` 结尾)
+     * @param {{create?: boolean, libPath?: string}} [opts]
+     */
+    constructor(path: string, opts?: {
+        create?: boolean;
+        libPath?: string;
+    });
+    path: string;
+    /**
+     * 查询文档。
+     * @template T
+     * @param {string} collection
+     * @param {object} [filter] MongoDB 风格过滤条件
+     * @param {{sort?: object, fields?: object, skip?: number, limit?: number}} [opts]
+     * @returns {T[]}
+     */
+    find<T>(collection: string, filter?: object, opts?: {
+        sort?: object;
+        fields?: object;
+        skip?: number;
+        limit?: number;
+    }): T[];
+    /**
+     * 分页查询:一次拿到「匹配总数 + 当页文档」,省掉单独 count。
+     * @template T
+     * @returns {{total: number, items: T[]}}
+     */
+    findPage<T>(collection: any, filter?: {}, opts?: {}): {
+        total: number;
+        items: T[];
+    };
+    /**
+     * 按 `_id` 读单条,不存在返回 `null`。
+     * @template T
+     * @returns {T | null}
+     */
+    get<T>(collection: any, id: any): T | null;
+    /** 计数。 */
+    count(collection: any, filter?: {}): number;
+    /** 列出全部集合名。 */
+    collections(): any;
+    /** 插入一条,返回 `_id`。 */
+    insert(collection: any, doc: any): any;
+    /** 批量插入(单事务),返回 `_id` 数组。 */
+    insertMany(collection: any, docs: any): any;
+    /** 更新,返回实际修改条数。 */
+    update(collection: any, filter: any, update: any): number;
+    /** 删除,返回删除条数。 */
+    delete(collection: any, filter: any): number;
+    /**
+     * 更新或插入。
+     * @returns {{updated: number} | {inserted: string}}
+     */
+    upsert(collection: any, filter: any, update: any): {
+        updated: number;
+    } | {
+        inserted: string;
+    };
+    /**
+     * 创建索引。
+     * @param {{unique?: boolean, sparse?: boolean, fields?: string[], directions?: number[]}} [opts]
+     *   传 `fields` 则为复合索引;否则用 `field`。
+     */
+    createIndex(collection: any, name: any, field: any, opts?: {
+        unique?: boolean;
+        sparse?: boolean;
+        fields?: string[];
+        directions?: number[];
+    }): any;
+    /** 列出索引定义。 */
+    listIndexes(collection: any): any;
+    /** 删除索引。 */
+    dropIndex(collection: any, name: any): boolean;
+    /**
+     * 查看查询计划。
+     * @returns {{stage: 'IXSCAN' | 'COLLSCAN', [k: string]: unknown}}
+     */
+    explain(collection: any, filter?: {}, sort?: null): {
+        stage: "IXSCAN" | "COLLSCAN";
+        [k: string]: unknown;
+    };
+    /** 关闭数据库。可重复调用。 */
+    close(): void;
+    /** 支持 `using db = new Database(...)` 自动关闭。 */
+    [Symbol.dispose](): void;
+    #private;
+}
+export { resolveLibPath };
+import { resolveLibPath } from './bindings.js';

package/dist/index.js

@@ -0,0 +1,233 @@
+// nodblite 的核心 API —— 同步风格,API 手感对齐 better-sqlite3。
+//
+// 为什么是同步的:C ABI 本身是同步的,套一层 Promise 只是把同步调用包进
+// 微任务,不会带来任何并发收益,反而让调用方多写 await。这与 better-sqlite3
+// 的判断一致。
+import { loadBindings, sliceToString, resolveLibPath } from './bindings.js';
+/** nodblite 错误码 → 错误类名。 */
+const ERROR_NAMES = {
+    1: 'DuplicateKeyError',
+    2: 'InvalidPathError',
+    3: 'InvalidFormatError',
+    4: 'VersionMismatchError',
+    5: 'InvalidCollectionError',
+    6: 'InvalidFilterError',
+    7: 'InvalidUpdateError',
+    8: 'InvalidSortError',
+    9: 'InvalidProjectionError',
+    10: 'InvalidDocumentError',
+    11: 'IoError',
+    99: 'InternalError',
+};
+/** 所有 nodblite 错误的基类。 */
+export class NodbliteError extends Error {
+    constructor(code, message, op) {
+        super(message || `nodblite 错误 ${code}`);
+        this.name = ERROR_NAMES[code] || 'NodbliteError';
+        this.code = code;
+        /** 出错的操作名,如 "insert" / "find"。 */
+        this.op = op || '';
+    }
+}
+/** 动态创建具体错误类,便于 `instanceof` 判断。 */
+export const Errors = Object.fromEntries(Object.values(ERROR_NAMES).map((name) => [
+    name,
+    class extends NodbliteError {
+        constructor(code, message, op) {
+            super(code, message, op);
+            this.name = name;
+        }
+    },
+]));
+function makeError(code, message, op) {
+    const Cls = Errors[ERROR_NAMES[code]] || NodbliteError;
+    return new Cls(code, message, op);
+}
+/**
+ * 一个 nodblite 数据库。
+ *
+ * 用法与 better-sqlite3 类似:
+ * ```js
+ * import { Database } from 'nodblite';
+ * const db = new Database('app.nodb');
+ * db.collection('users').insert({ name: '张三' });
+ * db.close();
+ * ```
+ */
+export class Database {
+    #f;
+    #db;
+    #closed = false;
+    /**
+     * @param {string} path 数据库文件路径(必须以 `.nodb` 结尾)
+     * @param {{create?: boolean, libPath?: string}} [opts]
+     */
+    constructor(path, opts = {}) {
+        if (!path || typeof path !== 'string') {
+            throw new TypeError('Database 需要一个文件路径');
+        }
+        if (!path.toLowerCase().endsWith('.nodb')) {
+            throw new Error(`文件后缀必须是 .nodb,收到: ${path}`);
+        }
+        this.#f = loadBindings(opts.libPath ?? resolveLibPath());
+        this.path = path;
+        this.#db = this.#f.open(path, opts.create === false ? 0 : 1);
+        if (!this.#db) {
+            throw makeError(this.#f.lastErrorCode(), this.#lastError(), 'open');
+        }
+    }
+    #lastError() {
+        const p = this.#f.lastError();
+        if (!p)
+            return '';
+        // lastError 返回 C 字符串指针;koffi 对 const char* 返回值已自动转成 string,
+        // 但也可能是裸指针,两种都兼容。
+        return typeof p === 'string' ? p : this.#f.koffi.decode(p, 'char');
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error('数据库已关闭');
+    }
+    /**
+     * 执行一次 C 调用并把结果拷成普通 JS 值。
+     *
+     * **关键**:`value` / `docs` 指向 arena 内部内存,必须在 `resultFree` 之前
+     * 全部拷出来,否则会读到已释放内存(表现为乱码或崩溃)。
+     */
+    #call(raw) {
+        this.#assertOpen();
+        if (!raw)
+            throw makeError(this.#f.lastErrorCode(), this.#lastError(), '');
+        try {
+            const r = this.#f.koffi.decode(raw, this.#f.Result);
+            if (r.code !== 0) {
+                throw makeError(r.code, this.#lastError(), '');
+            }
+            const { Slice, koffi } = this.#f;
+            return {
+                count: Number(r.count),
+                affected: Number(r.affected),
+                value: sliceToString(koffi, r.value),
+                docs: r.count === 0
+                    ? []
+                    : koffi.decode(r.docs, Slice, r.count).map((s) => sliceToString(koffi, s)),
+            };
+        }
+        finally {
+            this.#f.resultFree(raw);
+        }
+    }
+    // ==================== 读 ====================
+    /**
+     * 查询文档。
+     * @template T
+     * @param {string} collection
+     * @param {object} [filter] MongoDB 风格过滤条件
+     * @param {{sort?: object, fields?: object, skip?: number, limit?: number}} [opts]
+     * @returns {T[]}
+     */
+    find(collection, filter = {}, opts = {}) {
+        const r = this.#call(this.#f.find(this.#db, collection, JSON.stringify(filter), opts.sort ? JSON.stringify(opts.sort) : null, opts.fields ? JSON.stringify(opts.fields) : null, BigInt(opts.skip ?? 0), BigInt(opts.limit ?? 0)));
+        return r.docs.map((s) => JSON.parse(s));
+    }
+    /**
+     * 分页查询:一次拿到「匹配总数 + 当页文档」,省掉单独 count。
+     * @template T
+     * @returns {{total: number, items: T[]}}
+     */
+    findPage(collection, filter = {}, opts = {}) {
+        const r = this.#call(this.#f.findPage(this.#db, collection, JSON.stringify(filter), opts.sort ? JSON.stringify(opts.sort) : null, opts.fields ? JSON.stringify(opts.fields) : null, BigInt(opts.skip ?? 0), BigInt(opts.limit ?? 0), opts.limit == null ? 1 : 0));
+        return { total: r.affected, items: r.docs.map((s) => JSON.parse(s)) };
+    }
+    /**
+     * 按 `_id` 读单条,不存在返回 `null`。
+     * @template T
+     * @returns {T | null}
+     */
+    get(collection, id) {
+        const r = this.#call(this.#f.get(this.#db, collection, String(id)));
+        return r.value === '' ? null : JSON.parse(r.value);
+    }
+    /** 计数。 */
+    count(collection, filter = {}) {
+        return this.#call(this.#f.count(this.#db, collection, JSON.stringify(filter))).affected;
+    }
+    /** 列出全部集合名。 */
+    collections() {
+        return this.#call(this.#f.listCollections(this.#db)).docs.map((s) => JSON.parse(s));
+    }
+    // ==================== 写 ====================
+    /** 插入一条,返回 `_id`。 */
+    insert(collection, doc) {
+        return this.#call(this.#f.insert(this.#db, collection, JSON.stringify(doc))).value;
+    }
+    /** 批量插入(单事务),返回 `_id` 数组。 */
+    insertMany(collection, docs) {
+        if (!Array.isArray(docs))
+            throw new TypeError('insertMany 需要数组');
+        const r = this.#call(this.#f.insertMany(this.#db, collection, JSON.stringify(docs)));
+        return JSON.parse(r.value);
+    }
+    /** 更新,返回实际修改条数。 */
+    update(collection, filter, update) {
+        return this.#call(this.#f.update(this.#db, collection, JSON.stringify(filter), JSON.stringify(update))).affected;
+    }
+    /** 删除,返回删除条数。 */
+    delete(collection, filter) {
+        return this.#call(this.#f.delete(this.#db, collection, JSON.stringify(filter))).affected;
+    }
+    /**
+     * 更新或插入。
+     * @returns {{updated: number} | {inserted: string}}
+     */
+    upsert(collection, filter, update) {
+        const r = this.#call(this.#f.upsert(this.#db, collection, JSON.stringify(filter), JSON.stringify(update)));
+        return JSON.parse(r.value);
+    }
+    // ==================== 索引 ====================
+    /**
+     * 创建索引。
+     * @param {{unique?: boolean, sparse?: boolean, fields?: string[], directions?: number[]}} [opts]
+     *   传 `fields` 则为复合索引;否则用 `field`。
+     */
+    createIndex(collection, name, field, opts = {}) {
+        const unique = opts.unique ? 1 : 0;
+        const sparse = opts.sparse ? 1 : 0;
+        if (opts.fields && opts.fields.length > 0) {
+            const r = this.#call(this.#f.createIndexComposite(this.#db, collection, name, JSON.stringify(opts.fields), opts.directions ? JSON.stringify(opts.directions) : null, unique, sparse));
+            return r.value;
+        }
+        const r = this.#call(this.#f.createIndex(this.#db, collection, name, field, unique, sparse));
+        return r.value;
+    }
+    /** 列出索引定义。 */
+    listIndexes(collection) {
+        return JSON.parse(this.#call(this.#f.listIndexes(this.#db, collection)).value);
+    }
+    /** 删除索引。 */
+    dropIndex(collection, name) {
+        return this.#call(this.#f.dropIndex(this.#db, collection, name)).value === 'true';
+    }
+    /**
+     * 查看查询计划。
+     * @returns {{stage: 'IXSCAN' | 'COLLSCAN', [k: string]: unknown}}
+     */
+    explain(collection, filter = {}, sort = null) {
+        const r = this.#call(this.#f.explain(this.#db, collection, JSON.stringify(filter), sort ? JSON.stringify(sort) : null));
+        return JSON.parse(r.value);
+    }
+    // ==================== 生命周期 ====================
+    /** 关闭数据库。可重复调用。 */
+    close() {
+        if (this.#closed)
+            return;
+        this.#f.close(this.#db);
+        this.#db = null;
+        this.#closed = true;
+    }
+    /** 支持 `using db = new Database(...)` 自动关闭。 */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+export { resolveLibPath };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "nodblite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.7",
+  "description": "单文件 NoSQL 文档数据库 —— MongoDB 风格查询,零配置,无需服务进程",
+  "keywords": ["database", "nosql", "embedded", "document", "mongodb", "sqlite"],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Titor-Z/nosqlite"
+  },
+  "homepage": "https://titor-z.github.io/nosqlite/",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "prebuilds", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "koffi": "^2.9.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}