nedb-engine 7.2.0 → 8.8.8

package/index.d.ts

@@ -1,64 +1,64 @@
-// nedb-engine — public type surface.
-//
-// Runtime behavior (durable-mode auto-flush-on-exit) is added by the wrapper in
-// index.js; the type surface is exactly the generated native binding's.
-export * from './native';
-
-// ── wrap adapter family (wrap/*.js) ─────────────────────────────────────────
-
-/** Options accepted by every wrap_* constructor. */
-export interface WrapOptions {
-  /** Logical database name (default "default"). */
-  dbName?: string;
-  /** HTTP nedbd server (v1 AOF, `--dag` v2, `--dag-v3` v3). Overrides embedded DAG. */
-  nedbdUrl?: string;
-  /** Bearer token for nedbd (NEDBD_TOKEN on the server). */
-  nedbdToken?: string;
-  /** Durable DAG store directory (embedded mode). */
-  dagPath?: string;
-  /** 64-hex TMK → AES-256-GCM at-rest encryption (embedded DAG mode). */
-  dagTmk?: string;
-  /** Explicit NedbCore class (testing / custom builds). */
-  native?: unknown;
-}
-
-/** The `.nedb` attribute — full NEDB layer-2 API. */
-export interface NedbSurface {
-  register(pattern: string, collection: string, opts?: {
-    idExtractor?: (key: string) => string;
-    valueParser?: (raw: unknown) => Record<string, unknown>;
-    valueType?: 'string' | 'hash' | 'json';
-  }): NedbSurface;
-  backfill(opts?: { pattern?: string; collection?: string; batchSize?: number }): number;
-  shadowWrites: boolean;
-  readonly engineKind: 'dag-embedded' | 'nedbd-http' | 'aof-embedded';
-
-  put(coll: string, id: string, doc: Record<string, unknown>): Record<string, unknown>;
-  get(coll: string, id: string, asOf?: number): Record<string, unknown> | null;
-  query(nql: string): Array<Record<string, unknown>>;
-  createIndex(coll: string, field: string, kind?: string): void;
-  delete(coll: string, id: string): void;
-  link(frm: string, rel: string, to: string): void;
-  unlink(frm: string, rel: string, to: string): void;
-  neighbors(frm: string, rel: string, asOf?: number): string[];
-  inbound(to: string, rel: string, asOf?: number): string[];
-  verify(): boolean;
-  readonly head: string;
-  readonly seq: number;
-  checkpoint(): string;
-  /** DAG-native: latest node (null on non-DAG backends). */
-  tip(): Record<string, unknown> | null;
-  /** DAG-native: changefeed page, after_seq exclusive. */
-  since(afterSeq: number | bigint, limit?: number): {
-    nodes: Array<Record<string, unknown>>; from_seq: number; to_seq: number;
-    head_seq: number; has_more: boolean;
-  };
-  /** DAG-native: replication readiness. */
-  scanStatus(): { scan_complete: boolean; tip_seq: number; indexed_count: number; [k: string]: unknown };
-}
-
-export declare function wrapRedis<T extends object = object>(client: T, opts?: WrapOptions): T & { nedb: NedbSurface };
-export declare function wrapSqlite<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
-export declare function wrapMysql<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
-export declare function wrapPg<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
-export declare function wrapMongo<T extends object = object>(client: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+// nedb-engine — public type surface.
+//
+// Runtime behavior (durable-mode auto-flush-on-exit) is added by the wrapper in
+// index.js; the type surface is exactly the generated native binding's.
+export * from './native';
+
+// ── wrap adapter family (wrap/*.js) ─────────────────────────────────────────
+
+/** Options accepted by every wrap_* constructor. */
+export interface WrapOptions {
+  /** Logical database name (default "default"). */
+  dbName?: string;
+  /** HTTP nedbd server (v1 AOF, `--dag` v2, `--dag-v3` v3). Overrides embedded DAG. */
+  nedbdUrl?: string;
+  /** Bearer token for nedbd (NEDBD_TOKEN on the server). */
+  nedbdToken?: string;
+  /** Durable DAG store directory (embedded mode). */
+  dagPath?: string;
+  /** 64-hex TMK → AES-256-GCM at-rest encryption (embedded DAG mode). */
+  dagTmk?: string;
+  /** Explicit NedbCore class (testing / custom builds). */
+  native?: unknown;
+}
+
+/** The `.nedb` attribute — full NEDB layer-2 API. */
+export interface NedbSurface {
+  register(pattern: string, collection: string, opts?: {
+    idExtractor?: (key: string) => string;
+    valueParser?: (raw: unknown) => Record<string, unknown>;
+    valueType?: 'string' | 'hash' | 'json';
+  }): NedbSurface;
+  backfill(opts?: { pattern?: string; collection?: string; batchSize?: number }): number;
+  shadowWrites: boolean;
+  readonly engineKind: 'dag-embedded' | 'nedbd-http' | 'aof-embedded';
+
+  put(coll: string, id: string, doc: Record<string, unknown>): Record<string, unknown>;
+  get(coll: string, id: string, asOf?: number): Record<string, unknown> | null;
+  query(nql: string): Array<Record<string, unknown>>;
+  createIndex(coll: string, field: string, kind?: string): void;
+  delete(coll: string, id: string): void;
+  link(frm: string, rel: string, to: string): void;
+  unlink(frm: string, rel: string, to: string): void;
+  neighbors(frm: string, rel: string, asOf?: number): string[];
+  inbound(to: string, rel: string, asOf?: number): string[];
+  verify(): boolean;
+  readonly head: string;
+  readonly seq: number;
+  checkpoint(): string;
+  /** DAG-native: latest node (null on non-DAG backends). */
+  tip(): Record<string, unknown> | null;
+  /** DAG-native: changefeed page, after_seq exclusive. */
+  since(afterSeq: number | bigint, limit?: number): {
+    nodes: Array<Record<string, unknown>>; from_seq: number; to_seq: number;
+    head_seq: number; has_more: boolean;
+  };
+  /** DAG-native: replication readiness. */
+  scanStatus(): { scan_complete: boolean; tip_seq: number; indexed_count: number; [k: string]: unknown };
+}
+
+export declare function wrapRedis<T extends object = object>(client: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapSqlite<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapMysql<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapPg<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapMongo<T extends object = object>(client: T, opts?: WrapOptions): T & { nedb: NedbSurface };

package/index.js

@@ -1,84 +1,84 @@
-// SPDX-FileCopyrightText: 2026 INTERCHAINED LLC
-// SPDX-License-Identifier: BUSL-1.1
-// NEDB · © 2026 INTERCHAINED LLC × Eth-Interchained × Vex (Claude Opus 5)
-
-'use strict';
-// nedb-engine — durable-mode auto-flush-on-exit wrapper.
-//
-// The native addon (generated napi binding in ./native.js) exposes `NedbCore`.
-// A durable `NedbCore.open(path)` buffers writes in the engine's id-index WAL and
-// only makes them durable on `flush()`; a hard exit (Ctrl+C, `SIGTERM` from an
-// orchestrator, `pm2 stop`) that never runs an explicit flush would lose writes
-// staged since the last flush.
-//
-// We close that gap the libuv-cooperative way — `process.on('SIGINT'|'SIGTERM'
-// |'exit', () => db.flush())` — NOT a C-level signal handler inside the addon,
-// which would clobber libuv's own signal machinery. In-memory databases
-// (`new NedbCore()`) are never armed; there is nothing to flush.
-//
-// Escape hatch: set NEDB_NO_EXIT_FLUSH=1 to leave signal handling entirely to
-// the host app (it can still call `db.flush()` itself).
-//
-// © INTERCHAINED LLC × Vex (Interchained AI fleet: GLM · Claude · Opus · Fable · GPT-6)
-const native = require('./native.js');
-
-const Native = native.NedbCore;
-
-// The napi class defines `open` as a NON-writable, NON-configurable static, so the
-// 2.5.x wrapper's `NedbCore.open = …` threw ("Cannot assign to read only property")
-// — and CI's `napi build` was overwriting this file with the generated loader
-// anyway, so the published package never carried the wrapper at all. Both fixed
-// in 2.8.5: wrap by SUBCLASS (an own static on the subclass shadows the parent's),
-// build with `--js native.js` so this file survives, and gate the publish on
-// `NedbCore.__exitFlushWrapped` (see test/durability.test.mjs).
-let NedbCore = Native;
-if (Native && typeof Native.open === 'function' && !Native.__exitFlushWrapped) {
-  // Durable handles opened in this process. Strong refs: a durable DB is meant to
-  // live for the process, and we must be able to flush it on the way out.
-  const live = new Set();
-  let armed = false;
-
-  const flushAll = () => {
-    for (const db of live) {
-      try {
-        db.flush();
-      } catch (_) {
-        // Best-effort on shutdown — never throw out of an exit handler.
-      }
-    }
-  };
-
-  const arm = () => {
-    if (armed || process.env.NEDB_NO_EXIT_FLUSH) return;
-    armed = true;
-    // 'exit' fires on normal termination; handlers must be synchronous, and
-    // db.flush() is a synchronous native call — so this is safe and sufficient
-    // for clean exits and uncaught-exception exits.
-    process.on('exit', flushAll);
-    // Registering a SIGINT/SIGTERM listener SUPPRESSES Node's default
-    // termination, so once we listen we own the exit: flush, then terminate with
-    // the conventional 128+signum status.
-    const onSignal = (signum) => () => {
-      flushAll();
-      process.exit(128 + signum);
-    };
-    process.on('SIGINT', onSignal(2));
-    process.on('SIGTERM', onSignal(15));
-  };
-
-  NedbCore = class NedbCore extends Native {
-    static open(path) {
-      const db = Native.open(path);
-      live.add(db);
-      arm();
-      return db;
-    }
-  };
-  // Mark so a re-require (or a wrapped re-export) never double-wraps.
-  Object.defineProperty(NedbCore, '__exitFlushWrapped', { value: true, enumerable: false });
-}
-
-module.exports = { ...native, NedbCore };
-// Explicit named re-export so ESM `import { NedbCore } from 'nedb-engine'` (used
-// by the test suite) resolves the class through cjs-module-lexer.
-module.exports.NedbCore = NedbCore;
+// SPDX-FileCopyrightText: 2026 INTERCHAINED LLC
+// SPDX-License-Identifier: BUSL-1.1
+// NEDB · © 2026 INTERCHAINED LLC × Eth-Interchained × Vex (Claude Opus 5)
+
+'use strict';
+// nedb-engine — durable-mode auto-flush-on-exit wrapper.
+//
+// The native addon (generated napi binding in ./native.js) exposes `NedbCore`.
+// A durable `NedbCore.open(path)` buffers writes in the engine's id-index WAL and
+// only makes them durable on `flush()`; a hard exit (Ctrl+C, `SIGTERM` from an
+// orchestrator, `pm2 stop`) that never runs an explicit flush would lose writes
+// staged since the last flush.
+//
+// We close that gap the libuv-cooperative way — `process.on('SIGINT'|'SIGTERM'
+// |'exit', () => db.flush())` — NOT a C-level signal handler inside the addon,
+// which would clobber libuv's own signal machinery. In-memory databases
+// (`new NedbCore()`) are never armed; there is nothing to flush.
+//
+// Escape hatch: set NEDB_NO_EXIT_FLUSH=1 to leave signal handling entirely to
+// the host app (it can still call `db.flush()` itself).
+//
+// © INTERCHAINED LLC × Vex (Interchained AI fleet: GLM · Claude · Opus · Fable · GPT-6)
+const native = require('./native.js');
+
+const Native = native.NedbCore;
+
+// The napi class defines `open` as a NON-writable, NON-configurable static, so the
+// 2.5.x wrapper's `NedbCore.open = …` threw ("Cannot assign to read only property")
+// — and CI's `napi build` was overwriting this file with the generated loader
+// anyway, so the published package never carried the wrapper at all. Both fixed
+// in 2.8.5: wrap by SUBCLASS (an own static on the subclass shadows the parent's),
+// build with `--js native.js` so this file survives, and gate the publish on
+// `NedbCore.__exitFlushWrapped` (see test/durability.test.mjs).
+let NedbCore = Native;
+if (Native && typeof Native.open === 'function' && !Native.__exitFlushWrapped) {
+  // Durable handles opened in this process. Strong refs: a durable DB is meant to
+  // live for the process, and we must be able to flush it on the way out.
+  const live = new Set();
+  let armed = false;
+
+  const flushAll = () => {
+    for (const db of live) {
+      try {
+        db.flush();
+      } catch (_) {
+        // Best-effort on shutdown — never throw out of an exit handler.
+      }
+    }
+  };
+
+  const arm = () => {
+    if (armed || process.env.NEDB_NO_EXIT_FLUSH) return;
+    armed = true;
+    // 'exit' fires on normal termination; handlers must be synchronous, and
+    // db.flush() is a synchronous native call — so this is safe and sufficient
+    // for clean exits and uncaught-exception exits.
+    process.on('exit', flushAll);
+    // Registering a SIGINT/SIGTERM listener SUPPRESSES Node's default
+    // termination, so once we listen we own the exit: flush, then terminate with
+    // the conventional 128+signum status.
+    const onSignal = (signum) => () => {
+      flushAll();
+      process.exit(128 + signum);
+    };
+    process.on('SIGINT', onSignal(2));
+    process.on('SIGTERM', onSignal(15));
+  };
+
+  NedbCore = class NedbCore extends Native {
+    static open(path) {
+      const db = Native.open(path);
+      live.add(db);
+      arm();
+      return db;
+    }
+  };
+  // Mark so a re-require (or a wrapped re-export) never double-wraps.
+  Object.defineProperty(NedbCore, '__exitFlushWrapped', { value: true, enumerable: false });
+}
+
+module.exports = { ...native, NedbCore };
+// Explicit named re-export so ESM `import { NedbCore } from 'nedb-engine'` (used
+// by the test suite) resolves the class through cjs-module-lexer.
+module.exports.NedbCore = NedbCore;

package/native.d.ts

@@ -28,7 +28,31 @@ export declare class NedbCore {
   unlink(frm: string, rel: string, to: string): void
   get(coll: string, id: string): string | null
   getAsOf(coll: string, id: string, asOf: bigint): string | null
+  /**
+   * Run **neSQL** — PostgreSQL SQL, or NQL. The parameter keeps its
+   * `nqlStr` name because existing callers pass it; what CHANGED is what
+   * it accepts.
+   *
+   * This was NQL-only, and an earlier version of this comment defended
+   * that as avoiding the risk of widening an existing method. Wrong twice:
+   * routing is STRUCTURAL and TOTAL (NQL begins `FROM`; PostgreSQL has no
+   * `FROM`-initial statement), so there is no ambiguity to introduce — and
+   * SQL is the FRONT DOOR. A binding that answered `SELECT who FROM orders`
+   * with "expected keyword FROM" would reproduce, one layer down, the exact
+   * "NEDB does not understand SQL" experience neSQL exists to end.
+   */
   query(nqlStr: string): Array<string>
+  /**
+   * `query()` under the language's own name. One implementation; `query`
+   * delegates here.
+   *
+   * Routing comes from `nedb_engine::nesql::route`, the SAME function the
+   * `nesql` CLI and `POST /query` use. Three front doors, one decision about
+   * what a statement means.
+   */
+  nesql(statement: string): Array<string>
+  /** Which half of neSQL a statement is written in: `"nql"` or `"sql"`. */
+  nesqlDialect(statement: string): string
   neighbors(frm: string, rel: string): Array<string>
   neighborsAsOf(frm: string, rel: string, asOf: bigint): Array<string>
   inbound(to: string, rel: string): Array<string>

package/nesql.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: 2026 INTERCHAINED LLC
+// SPDX-License-Identifier: BUSL-1.1
+// NEDB · © 2026 INTERCHAINED LLC × Eth-Interchained × Vex (Claude Opus 5)
+
+// nesql — thin platform shim that locates and spawns the prebuilt neSQL CLI
+// binary for the current platform/arch.
+//
+// The binaries ship alongside this file in the npm package root, using the
+// same naming convention as nedbd-v2 so the release workflow stages both the
+// same way:
+//
+//   Linux x64    -> nesql-linux-x64
+//   Windows x64  -> nesql-win-x64.exe
+//   macOS arm64  -> nesql-darwin-arm64
+//   macOS x64    -> nesql-darwin-x64
+//
+// # The exit code is the contract
+//
+// `nesql` distinguishes 0 success / 1 failure / 2 usage / 3 could-not-determine
+// / 4 not found / 5 unsupported, and callers script against those. So this shim
+// propagates the child's code EXACTLY and never substitutes one of its own for
+// a successful spawn. `npx nesql …` has to be indistinguishable from invoking
+// the binary, or the codes stop meaning anything.
+//
+// A shim failure — unsupported platform, missing binary — exits 5
+// (unsupported), which is the CLI's own word for "this build cannot do that".
+// Exiting 1 would claim the command ran and failed.
+
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const SUPPORTED = {
+  "linux-x64": "nesql-linux-x64",
+  "win32-x64": "nesql-win-x64.exe",
+  "darwin-arm64": "nesql-darwin-arm64",
+  "darwin-x64": "nesql-darwin-x64",
+};
+
+function main() {
+  const key = `${process.platform}-${process.arch}`;
+  const name = SUPPORTED[key];
+
+  if (!name) {
+    process.stderr.write(
+      `nesql: unsupported platform/arch: ${key}\n` +
+        `Supported: ${Object.keys(SUPPORTED).join(", ")}\n` +
+        `Build from source instead:  cargo install nesql\n`
+    );
+    process.exit(5);
+  }
+
+  const binPath = path.join(__dirname, name);
+  if (!fs.existsSync(binPath)) {
+    process.stderr.write(
+      `nesql: the prebuilt binary is missing for this platform.\n` +
+        `  expected: ${binPath}\n` +
+        `  platform: ${key}\n\n` +
+        `This nedb-engine install did not include it. Fixes:\n` +
+        `  npm install --force nedb-engine\n` +
+        `  cargo install nesql        # builds from source, any platform\n`
+    );
+    process.exit(5);
+  }
+
+  const child = spawn(binPath, process.argv.slice(2), { stdio: "inherit" });
+
+  child.on("error", (err) => {
+    // Named rather than swallowed: a spawn failure and a non-zero exit from a
+    // binary that DID run are different diagnoses, and collapsing them sends
+    // the reader looking in the wrong place.
+    process.stderr.write(`nesql: failed to execute ${binPath}: ${err.message}\n`);
+    process.exit(5);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      // Reproduce the signal death rather than translating it to a number,
+      // so a Ctrl-C through npx behaves like a Ctrl-C to the binary.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 5 : code);
+  });
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nedb-engine",
-  "version": "7.2.0",
+  "version": "8.8.8",
   "description": "NEDB \u2014 hash-chained, time-traveling, bi-temporal embedded database with Rust native core. SQL, Redis, MongoDB adapters. Causal Write Provenance. RESP2 wire protocol.",
   "main": "index.js",
   "exports": {
@@ -14,7 +14,8 @@
   "bin": {
     "nedbd-v2": "./nedbd-v2.js",
     "nedbdv2": "./nedbd-v2.js",
-    "nedb-inspector": "./nedb-inspector.mjs"
+    "nedb-inspector": "./nedb-inspector.mjs",
+    "nesql": "./nesql.js"
   },
   "files": [
     "index.js",
@@ -29,7 +30,9 @@
     "test/smoke.mjs",
     "test/durability.test.mjs",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "nesql.js",
+    "nesql-*"
   ],
   "license": "BUSL-1.1",
   "homepage": "https://github.com/aiassistsecure/nedb#readme",