@noy-db/as-ndjson 0.1.0-pre.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @noy-db/as-ndjson
+
+[![npm](https://img.shields.io/npm/v/%40noy-db/as-ndjson.svg)](https://www.npmjs.com/package/@noy-db/as-ndjson)
+
+> Newline-delimited JSON export for noy-db
+
+Part of [**`@noy-db/hub`**](https://www.npmjs.com/package/@noy-db/hub) — the zero-knowledge, offline-first, encrypted document store.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/as-ndjson
+```
+
+## What it is
+
+Newline-delimited JSON export for noy-db — streaming plaintext export suitable for data pipelines, warehouse ingestion, and jq pipelines. Gated by RFC #249 canExportPlaintext. Part of the @noy-db/as-* portable-artefact family (plaintext tier).
+
+## Status
+
+**Pre-release** (`0.1.0-pre.1`). API may change before `1.0`.
+
+## Documentation
+
+See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
+
+- Source — [`packages/as-ndjson`](https://github.com/vLannaAi/noy-db/tree/main/packages/as-ndjson)
+- Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db/blob/main/SPEC.md)
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/index.cjs

@@ -0,0 +1,135 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  download: () => download,
+  fromString: () => fromString,
+  pipe: () => pipe,
+  stream: () => stream,
+  toString: () => toString
+});
+module.exports = __toCommonJS(index_exports);
+var import_hub = require("@noy-db/hub");
+async function* stream(vault, options = {}) {
+  vault.assertCanExport("plaintext", "ndjson");
+  const allowlist = options.collections ? new Set(options.collections) : null;
+  const schemaField = options.schemaField ?? "_schema";
+  for await (const chunk of vault.exportStream({ granularity: "record" })) {
+    if (allowlist && !allowlist.has(chunk.collection)) continue;
+    for (const record of chunk.records) {
+      const base = options.includeMeta ? record : stripMeta(record);
+      const out = { [schemaField]: chunk.collection, ...base };
+      yield JSON.stringify(out);
+    }
+  }
+}
+async function toString(vault, options = {}) {
+  const lines = [];
+  for await (const line of stream(vault, options)) lines.push(line);
+  return lines.join("\n");
+}
+async function download(vault, options = {}) {
+  const ndjson = await toString(vault, options);
+  const filename = options.filename ?? "vault-export.ndjson";
+  const blob = new Blob([ndjson + "\n"], { type: "application/x-ndjson;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+async function pipe(vault, sink, options) {
+  if (options.acknowledgeRisks !== true) {
+    throw new Error(
+      'as-ndjson.pipe: acknowledgeRisks: true is required for on-disk plaintext output. See docs/patterns/as-exports.md \xA7"The three tiers of \\"plaintext out\\""'
+    );
+  }
+  for await (const line of stream(vault, options)) {
+    sink.write(line + "\n");
+  }
+  sink.end?.();
+}
+function stripMeta(record) {
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "_v" || key === "_ts" || key === "_by" || key === "_iv" || key === "_data" || key === "_noydb") continue;
+    out[key] = value;
+  }
+  return out;
+}
+async function fromString(vault, ndjson, options) {
+  vault.assertCanImport("plaintext", "ndjson");
+  const policy = options.policy ?? "merge";
+  const idKey = options.idKey ?? "id";
+  const records = [];
+  let lineNo = 0;
+  for (const raw of ndjson.split("\n")) {
+    lineNo++;
+    const line = raw.trim();
+    if (!line) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (err) {
+      throw new Error(`as-ndjson.fromString: malformed JSON on line ${lineNo}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`as-ndjson.fromString: line ${lineNo} is not a JSON object`);
+    }
+    records.push(parsed);
+  }
+  const plan = await (0, import_hub.diffVault)(vault, { [options.collection]: records }, {
+    collections: [options.collection],
+    idKey
+  });
+  return {
+    plan,
+    policy,
+    async apply() {
+      await vault.noydb.transaction((tx) => {
+        const txVault = tx.vault(vault.name);
+        for (const entry of plan.added) {
+          txVault.collection(entry.collection).put(entry.id, entry.record);
+        }
+        if (policy !== "insert-only") {
+          for (const entry of plan.modified) {
+            txVault.collection(entry.collection).put(entry.id, entry.record);
+          }
+        }
+        if (policy === "replace") {
+          for (const entry of plan.deleted) {
+            txVault.collection(entry.collection).delete(entry.id);
+          }
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  download,
+  fromString,
+  pipe,
+  stream,
+  toString
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/as-ndjson** — newline-delimited JSON plaintext export.\n *\n * Streaming-friendly sibling to `@noy-db/as-json`. Emits one JSON\n * object per line, each carrying a `_schema` field naming the source\n * collection so a downstream reader can route records without a\n * separate header pass:\n *\n * ```\n * {\"_schema\":\"invoices\",\"id\":\"i1\",\"amount\":100,...}\n * {\"_schema\":\"invoices\",\"id\":\"i2\",\"amount\":250,...}\n * {\"_schema\":\"payments\",\"id\":\"p1\",\"invoiceId\":\"i1\",\"amount\":100,...}\n * ```\n *\n * Best for large vaults (10K+ records) where loading a single JSON\n * array into memory is clumsy. Pipes cleanly into `jq`, `fx`, log\n * stacks, or any line-oriented reducer.\n *\n * @packageDocumentation\n */\n\nimport type { Vault } from '@noy-db/hub'\n\nexport interface AsNDJSONOptions {\n  /** Collection allowlist. Omit for every collection the caller can read. */\n  readonly collections?: readonly string[]\n  /** Include envelope metadata (`_v`, `_ts`, `_by`) on each line. Default `false`. */\n  readonly includeMeta?: boolean\n  /** Name of the routing field. Default `'_schema'`. */\n  readonly schemaField?: string\n}\n\nexport interface AsNDJSONDownloadOptions extends AsNDJSONOptions {\n  /** Filename offered to the browser. Default `'vault-export.ndjson'`. */\n  readonly filename?: string\n}\n\nexport interface AsNDJSONWriteOptions extends AsNDJSONOptions {\n  /** Required to write plaintext NDJSON to disk — Tier 3 risk gate. */\n  readonly acknowledgeRisks: true\n}\n\n/**\n * Async iterator emitting one NDJSON-formatted line per record (no\n * trailing newline — the caller decides). The authorization check\n * runs before the first record is produced.\n */\nexport async function* stream(vault: Vault, options: AsNDJSONOptions = {}): AsyncGenerator<string> {\n  vault.assertCanExport('plaintext', 'ndjson')\n  const allowlist = options.collections ? new Set(options.collections) : null\n  const schemaField = options.schemaField ?? '_schema'\n\n  for await (const chunk of vault.exportStream({ granularity: 'record' })) {\n    if (allowlist && !allowlist.has(chunk.collection)) continue\n    for (const record of chunk.records) {\n      const base = options.includeMeta\n        ? (record as Record<string, unknown>)\n        : stripMeta(record as Record<string, unknown>)\n      const out: Record<string, unknown> = { [schemaField]: chunk.collection, ...base }\n      yield JSON.stringify(out)\n    }\n  }\n}\n\n/** Collect the full NDJSON export into a single string (in-memory). */\nexport async function toString(vault: Vault, options: AsNDJSONOptions = {}): Promise<string> {\n  const lines: string[] = []\n  for await (const line of stream(vault, options)) lines.push(line)\n  return lines.join('\\n')\n}\n\n/** Browser download wrapping `toString()` in a Blob save-as prompt. */\nexport async function download(vault: Vault, options: AsNDJSONDownloadOptions = {}): Promise<void> {\n  const ndjson = await toString(vault, options)\n  const filename = options.filename ?? 'vault-export.ndjson'\n  const blob = new Blob([ndjson + '\\n'], { type: 'application/x-ndjson;charset=utf-8' })\n  const url = URL.createObjectURL(blob)\n  const a = document.createElement('a')\n  a.href = url\n  a.download = filename\n  a.click()\n  URL.revokeObjectURL(url)\n}\n\n/**\n * Node pipe: stream each line into a WritableStream-like sink (a\n * `fs.WriteStream`, `process.stdout`, or any `.write(chunk)` +\n * `.end()` duck). Memory usage is O(one record) regardless of vault\n * size.\n */\nexport async function pipe(\n  vault: Vault,\n  sink: { write(chunk: string): unknown; end?(): void },\n  options: AsNDJSONWriteOptions,\n): Promise<void> {\n  if (options.acknowledgeRisks !== true) {\n    throw new Error(\n      'as-ndjson.pipe: acknowledgeRisks: true is required for on-disk plaintext output. ' +\n      'See docs/patterns/as-exports.md §\"The three tiers of \\\\\"plaintext out\\\\\"\"',\n    )\n  }\n  for await (const line of stream(vault, options)) {\n    sink.write(line + '\\n')\n  }\n  sink.end?.()\n}\n\nfunction stripMeta(record: Record<string, unknown>): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n  for (const [key, value] of Object.entries(record)) {\n    if (key === '_v' || key === '_ts' || key === '_by' || key === '_iv' || key === '_data' || key === '_noydb') continue\n    out[key] = value\n  }\n  return out\n}\n\n// ─── Reader ─────────────────────────────────────────────\n\nimport { diffVault, type VaultDiff } from '@noy-db/hub'\n\nexport type ImportPolicy = 'merge' | 'replace' | 'insert-only'\n\nexport interface AsNDJSONImportOptions {\n  /**\n   * Target collection. NDJSON is one record per line — every record\n   * lands in the same collection. Required.\n   */\n  readonly collection: string\n  /** Field on each record that carries its id. Default `'id'`. */\n  readonly idKey?: string\n  /** Reconciliation policy. Default `'merge'`. */\n  readonly policy?: ImportPolicy\n}\n\nexport interface AsNDJSONImportPlan {\n  readonly plan: VaultDiff\n  readonly policy: ImportPolicy\n  apply(): Promise<void>\n}\n\n/**\n * Parse newline-delimited JSON into records and build an import plan\n * for one collection. Empty lines and lines with leading whitespace\n * are ignored. A single malformed line throws — callers that want\n * lenient parsing can pre-filter their input.\n */\nexport async function fromString(\n  vault: Vault,\n  ndjson: string,\n  options: AsNDJSONImportOptions,\n): Promise<AsNDJSONImportPlan> {\n  vault.assertCanImport('plaintext', 'ndjson')\n  const policy: ImportPolicy = options.policy ?? 'merge'\n  const idKey = options.idKey ?? 'id'\n\n  const records: Record<string, unknown>[] = []\n  let lineNo = 0\n  for (const raw of ndjson.split('\\n')) {\n    lineNo++\n    const line = raw.trim()\n    if (!line) continue\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(line)\n    } catch (err) {\n      throw new Error(`as-ndjson.fromString: malformed JSON on line ${lineNo}: ${(err as Error).message}`)\n    }\n    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n      throw new Error(`as-ndjson.fromString: line ${lineNo} is not a JSON object`)\n    }\n    records.push(parsed as Record<string, unknown>)\n  }\n\n  const plan = await diffVault(vault, { [options.collection]: records }, {\n    collections: [options.collection],\n    idKey,\n  })\n\n  return {\n    plan,\n    policy,\n    async apply(): Promise<void> {\n      // Routes through the txStrategy seam — throws clearly when\n      // withTransactions() isn't opted in. Atomicity rolls back any\n      // partial writes if a put fails mid-batch.\n      await vault.noydb.transaction((tx) => {\n        const txVault = tx.vault(vault.name)\n        for (const entry of plan.added) {\n          txVault.collection(entry.collection).put(entry.id, entry.record)\n        }\n        if (policy !== 'insert-only') {\n          for (const entry of plan.modified) {\n            txVault.collection(entry.collection).put(entry.id, entry.record)\n          }\n        }\n        if (policy === 'replace') {\n          for (const entry of plan.deleted) {\n            txVault.collection(entry.collection).delete(entry.id)\n          }\n        }\n      })\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,86 @@
+import { VaultDiff, Vault } from '@noy-db/hub';
+
+/**
+ * **@noy-db/as-ndjson** — newline-delimited JSON plaintext export.
+ *
+ * Streaming-friendly sibling to `@noy-db/as-json`. Emits one JSON
+ * object per line, each carrying a `_schema` field naming the source
+ * collection so a downstream reader can route records without a
+ * separate header pass:
+ *
+ * ```
+ * {"_schema":"invoices","id":"i1","amount":100,...}
+ * {"_schema":"invoices","id":"i2","amount":250,...}
+ * {"_schema":"payments","id":"p1","invoiceId":"i1","amount":100,...}
+ * ```
+ *
+ * Best for large vaults (10K+ records) where loading a single JSON
+ * array into memory is clumsy. Pipes cleanly into `jq`, `fx`, log
+ * stacks, or any line-oriented reducer.
+ *
+ * @packageDocumentation
+ */
+
+interface AsNDJSONOptions {
+    /** Collection allowlist. Omit for every collection the caller can read. */
+    readonly collections?: readonly string[];
+    /** Include envelope metadata (`_v`, `_ts`, `_by`) on each line. Default `false`. */
+    readonly includeMeta?: boolean;
+    /** Name of the routing field. Default `'_schema'`. */
+    readonly schemaField?: string;
+}
+interface AsNDJSONDownloadOptions extends AsNDJSONOptions {
+    /** Filename offered to the browser. Default `'vault-export.ndjson'`. */
+    readonly filename?: string;
+}
+interface AsNDJSONWriteOptions extends AsNDJSONOptions {
+    /** Required to write plaintext NDJSON to disk — Tier 3 risk gate. */
+    readonly acknowledgeRisks: true;
+}
+/**
+ * Async iterator emitting one NDJSON-formatted line per record (no
+ * trailing newline — the caller decides). The authorization check
+ * runs before the first record is produced.
+ */
+declare function stream(vault: Vault, options?: AsNDJSONOptions): AsyncGenerator<string>;
+/** Collect the full NDJSON export into a single string (in-memory). */
+declare function toString(vault: Vault, options?: AsNDJSONOptions): Promise<string>;
+/** Browser download wrapping `toString()` in a Blob save-as prompt. */
+declare function download(vault: Vault, options?: AsNDJSONDownloadOptions): Promise<void>;
+/**
+ * Node pipe: stream each line into a WritableStream-like sink (a
+ * `fs.WriteStream`, `process.stdout`, or any `.write(chunk)` +
+ * `.end()` duck). Memory usage is O(one record) regardless of vault
+ * size.
+ */
+declare function pipe(vault: Vault, sink: {
+    write(chunk: string): unknown;
+    end?(): void;
+}, options: AsNDJSONWriteOptions): Promise<void>;
+
+type ImportPolicy = 'merge' | 'replace' | 'insert-only';
+interface AsNDJSONImportOptions {
+    /**
+     * Target collection. NDJSON is one record per line — every record
+     * lands in the same collection. Required.
+     */
+    readonly collection: string;
+    /** Field on each record that carries its id. Default `'id'`. */
+    readonly idKey?: string;
+    /** Reconciliation policy. Default `'merge'`. */
+    readonly policy?: ImportPolicy;
+}
+interface AsNDJSONImportPlan {
+    readonly plan: VaultDiff;
+    readonly policy: ImportPolicy;
+    apply(): Promise<void>;
+}
+/**
+ * Parse newline-delimited JSON into records and build an import plan
+ * for one collection. Empty lines and lines with leading whitespace
+ * are ignored. A single malformed line throws — callers that want
+ * lenient parsing can pre-filter their input.
+ */
+declare function fromString(vault: Vault, ndjson: string, options: AsNDJSONImportOptions): Promise<AsNDJSONImportPlan>;
+
+export { type AsNDJSONDownloadOptions, type AsNDJSONImportOptions, type AsNDJSONImportPlan, type AsNDJSONOptions, type AsNDJSONWriteOptions, type ImportPolicy, download, fromString, pipe, stream, toString };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { VaultDiff, Vault } from '@noy-db/hub';
+
+/**
+ * **@noy-db/as-ndjson** — newline-delimited JSON plaintext export.
+ *
+ * Streaming-friendly sibling to `@noy-db/as-json`. Emits one JSON
+ * object per line, each carrying a `_schema` field naming the source
+ * collection so a downstream reader can route records without a
+ * separate header pass:
+ *
+ * ```
+ * {"_schema":"invoices","id":"i1","amount":100,...}
+ * {"_schema":"invoices","id":"i2","amount":250,...}
+ * {"_schema":"payments","id":"p1","invoiceId":"i1","amount":100,...}
+ * ```
+ *
+ * Best for large vaults (10K+ records) where loading a single JSON
+ * array into memory is clumsy. Pipes cleanly into `jq`, `fx`, log
+ * stacks, or any line-oriented reducer.
+ *
+ * @packageDocumentation
+ */
+
+interface AsNDJSONOptions {
+    /** Collection allowlist. Omit for every collection the caller can read. */
+    readonly collections?: readonly string[];
+    /** Include envelope metadata (`_v`, `_ts`, `_by`) on each line. Default `false`. */
+    readonly includeMeta?: boolean;
+    /** Name of the routing field. Default `'_schema'`. */
+    readonly schemaField?: string;
+}
+interface AsNDJSONDownloadOptions extends AsNDJSONOptions {
+    /** Filename offered to the browser. Default `'vault-export.ndjson'`. */
+    readonly filename?: string;
+}
+interface AsNDJSONWriteOptions extends AsNDJSONOptions {
+    /** Required to write plaintext NDJSON to disk — Tier 3 risk gate. */
+    readonly acknowledgeRisks: true;
+}
+/**
+ * Async iterator emitting one NDJSON-formatted line per record (no
+ * trailing newline — the caller decides). The authorization check
+ * runs before the first record is produced.
+ */
+declare function stream(vault: Vault, options?: AsNDJSONOptions): AsyncGenerator<string>;
+/** Collect the full NDJSON export into a single string (in-memory). */
+declare function toString(vault: Vault, options?: AsNDJSONOptions): Promise<string>;
+/** Browser download wrapping `toString()` in a Blob save-as prompt. */
+declare function download(vault: Vault, options?: AsNDJSONDownloadOptions): Promise<void>;
+/**
+ * Node pipe: stream each line into a WritableStream-like sink (a
+ * `fs.WriteStream`, `process.stdout`, or any `.write(chunk)` +
+ * `.end()` duck). Memory usage is O(one record) regardless of vault
+ * size.
+ */
+declare function pipe(vault: Vault, sink: {
+    write(chunk: string): unknown;
+    end?(): void;
+}, options: AsNDJSONWriteOptions): Promise<void>;
+
+type ImportPolicy = 'merge' | 'replace' | 'insert-only';
+interface AsNDJSONImportOptions {
+    /**
+     * Target collection. NDJSON is one record per line — every record
+     * lands in the same collection. Required.
+     */
+    readonly collection: string;
+    /** Field on each record that carries its id. Default `'id'`. */
+    readonly idKey?: string;
+    /** Reconciliation policy. Default `'merge'`. */
+    readonly policy?: ImportPolicy;
+}
+interface AsNDJSONImportPlan {
+    readonly plan: VaultDiff;
+    readonly policy: ImportPolicy;
+    apply(): Promise<void>;
+}
+/**
+ * Parse newline-delimited JSON into records and build an import plan
+ * for one collection. Empty lines and lines with leading whitespace
+ * are ignored. A single malformed line throws — callers that want
+ * lenient parsing can pre-filter their input.
+ */
+declare function fromString(vault: Vault, ndjson: string, options: AsNDJSONImportOptions): Promise<AsNDJSONImportPlan>;
+
+export { type AsNDJSONDownloadOptions, type AsNDJSONImportOptions, type AsNDJSONImportPlan, type AsNDJSONOptions, type AsNDJSONWriteOptions, type ImportPolicy, download, fromString, pipe, stream, toString };

package/dist/index.js

@@ -0,0 +1,106 @@
+// src/index.ts
+import { diffVault } from "@noy-db/hub";
+async function* stream(vault, options = {}) {
+  vault.assertCanExport("plaintext", "ndjson");
+  const allowlist = options.collections ? new Set(options.collections) : null;
+  const schemaField = options.schemaField ?? "_schema";
+  for await (const chunk of vault.exportStream({ granularity: "record" })) {
+    if (allowlist && !allowlist.has(chunk.collection)) continue;
+    for (const record of chunk.records) {
+      const base = options.includeMeta ? record : stripMeta(record);
+      const out = { [schemaField]: chunk.collection, ...base };
+      yield JSON.stringify(out);
+    }
+  }
+}
+async function toString(vault, options = {}) {
+  const lines = [];
+  for await (const line of stream(vault, options)) lines.push(line);
+  return lines.join("\n");
+}
+async function download(vault, options = {}) {
+  const ndjson = await toString(vault, options);
+  const filename = options.filename ?? "vault-export.ndjson";
+  const blob = new Blob([ndjson + "\n"], { type: "application/x-ndjson;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+async function pipe(vault, sink, options) {
+  if (options.acknowledgeRisks !== true) {
+    throw new Error(
+      'as-ndjson.pipe: acknowledgeRisks: true is required for on-disk plaintext output. See docs/patterns/as-exports.md \xA7"The three tiers of \\"plaintext out\\""'
+    );
+  }
+  for await (const line of stream(vault, options)) {
+    sink.write(line + "\n");
+  }
+  sink.end?.();
+}
+function stripMeta(record) {
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "_v" || key === "_ts" || key === "_by" || key === "_iv" || key === "_data" || key === "_noydb") continue;
+    out[key] = value;
+  }
+  return out;
+}
+async function fromString(vault, ndjson, options) {
+  vault.assertCanImport("plaintext", "ndjson");
+  const policy = options.policy ?? "merge";
+  const idKey = options.idKey ?? "id";
+  const records = [];
+  let lineNo = 0;
+  for (const raw of ndjson.split("\n")) {
+    lineNo++;
+    const line = raw.trim();
+    if (!line) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (err) {
+      throw new Error(`as-ndjson.fromString: malformed JSON on line ${lineNo}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`as-ndjson.fromString: line ${lineNo} is not a JSON object`);
+    }
+    records.push(parsed);
+  }
+  const plan = await diffVault(vault, { [options.collection]: records }, {
+    collections: [options.collection],
+    idKey
+  });
+  return {
+    plan,
+    policy,
+    async apply() {
+      await vault.noydb.transaction((tx) => {
+        const txVault = tx.vault(vault.name);
+        for (const entry of plan.added) {
+          txVault.collection(entry.collection).put(entry.id, entry.record);
+        }
+        if (policy !== "insert-only") {
+          for (const entry of plan.modified) {
+            txVault.collection(entry.collection).put(entry.id, entry.record);
+          }
+        }
+        if (policy === "replace") {
+          for (const entry of plan.deleted) {
+            txVault.collection(entry.collection).delete(entry.id);
+          }
+        }
+      });
+    }
+  };
+}
+export {
+  download,
+  fromString,
+  pipe,
+  stream,
+  toString
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/as-ndjson** — newline-delimited JSON plaintext export.\n *\n * Streaming-friendly sibling to `@noy-db/as-json`. Emits one JSON\n * object per line, each carrying a `_schema` field naming the source\n * collection so a downstream reader can route records without a\n * separate header pass:\n *\n * ```\n * {\"_schema\":\"invoices\",\"id\":\"i1\",\"amount\":100,...}\n * {\"_schema\":\"invoices\",\"id\":\"i2\",\"amount\":250,...}\n * {\"_schema\":\"payments\",\"id\":\"p1\",\"invoiceId\":\"i1\",\"amount\":100,...}\n * ```\n *\n * Best for large vaults (10K+ records) where loading a single JSON\n * array into memory is clumsy. Pipes cleanly into `jq`, `fx`, log\n * stacks, or any line-oriented reducer.\n *\n * @packageDocumentation\n */\n\nimport type { Vault } from '@noy-db/hub'\n\nexport interface AsNDJSONOptions {\n  /** Collection allowlist. Omit for every collection the caller can read. */\n  readonly collections?: readonly string[]\n  /** Include envelope metadata (`_v`, `_ts`, `_by`) on each line. Default `false`. */\n  readonly includeMeta?: boolean\n  /** Name of the routing field. Default `'_schema'`. */\n  readonly schemaField?: string\n}\n\nexport interface AsNDJSONDownloadOptions extends AsNDJSONOptions {\n  /** Filename offered to the browser. Default `'vault-export.ndjson'`. */\n  readonly filename?: string\n}\n\nexport interface AsNDJSONWriteOptions extends AsNDJSONOptions {\n  /** Required to write plaintext NDJSON to disk — Tier 3 risk gate. */\n  readonly acknowledgeRisks: true\n}\n\n/**\n * Async iterator emitting one NDJSON-formatted line per record (no\n * trailing newline — the caller decides). The authorization check\n * runs before the first record is produced.\n */\nexport async function* stream(vault: Vault, options: AsNDJSONOptions = {}): AsyncGenerator<string> {\n  vault.assertCanExport('plaintext', 'ndjson')\n  const allowlist = options.collections ? new Set(options.collections) : null\n  const schemaField = options.schemaField ?? '_schema'\n\n  for await (const chunk of vault.exportStream({ granularity: 'record' })) {\n    if (allowlist && !allowlist.has(chunk.collection)) continue\n    for (const record of chunk.records) {\n      const base = options.includeMeta\n        ? (record as Record<string, unknown>)\n        : stripMeta(record as Record<string, unknown>)\n      const out: Record<string, unknown> = { [schemaField]: chunk.collection, ...base }\n      yield JSON.stringify(out)\n    }\n  }\n}\n\n/** Collect the full NDJSON export into a single string (in-memory). */\nexport async function toString(vault: Vault, options: AsNDJSONOptions = {}): Promise<string> {\n  const lines: string[] = []\n  for await (const line of stream(vault, options)) lines.push(line)\n  return lines.join('\\n')\n}\n\n/** Browser download wrapping `toString()` in a Blob save-as prompt. */\nexport async function download(vault: Vault, options: AsNDJSONDownloadOptions = {}): Promise<void> {\n  const ndjson = await toString(vault, options)\n  const filename = options.filename ?? 'vault-export.ndjson'\n  const blob = new Blob([ndjson + '\\n'], { type: 'application/x-ndjson;charset=utf-8' })\n  const url = URL.createObjectURL(blob)\n  const a = document.createElement('a')\n  a.href = url\n  a.download = filename\n  a.click()\n  URL.revokeObjectURL(url)\n}\n\n/**\n * Node pipe: stream each line into a WritableStream-like sink (a\n * `fs.WriteStream`, `process.stdout`, or any `.write(chunk)` +\n * `.end()` duck). Memory usage is O(one record) regardless of vault\n * size.\n */\nexport async function pipe(\n  vault: Vault,\n  sink: { write(chunk: string): unknown; end?(): void },\n  options: AsNDJSONWriteOptions,\n): Promise<void> {\n  if (options.acknowledgeRisks !== true) {\n    throw new Error(\n      'as-ndjson.pipe: acknowledgeRisks: true is required for on-disk plaintext output. ' +\n      'See docs/patterns/as-exports.md §\"The three tiers of \\\\\"plaintext out\\\\\"\"',\n    )\n  }\n  for await (const line of stream(vault, options)) {\n    sink.write(line + '\\n')\n  }\n  sink.end?.()\n}\n\nfunction stripMeta(record: Record<string, unknown>): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n  for (const [key, value] of Object.entries(record)) {\n    if (key === '_v' || key === '_ts' || key === '_by' || key === '_iv' || key === '_data' || key === '_noydb') continue\n    out[key] = value\n  }\n  return out\n}\n\n// ─── Reader ─────────────────────────────────────────────\n\nimport { diffVault, type VaultDiff } from '@noy-db/hub'\n\nexport type ImportPolicy = 'merge' | 'replace' | 'insert-only'\n\nexport interface AsNDJSONImportOptions {\n  /**\n   * Target collection. NDJSON is one record per line — every record\n   * lands in the same collection. Required.\n   */\n  readonly collection: string\n  /** Field on each record that carries its id. Default `'id'`. */\n  readonly idKey?: string\n  /** Reconciliation policy. Default `'merge'`. */\n  readonly policy?: ImportPolicy\n}\n\nexport interface AsNDJSONImportPlan {\n  readonly plan: VaultDiff\n  readonly policy: ImportPolicy\n  apply(): Promise<void>\n}\n\n/**\n * Parse newline-delimited JSON into records and build an import plan\n * for one collection. Empty lines and lines with leading whitespace\n * are ignored. A single malformed line throws — callers that want\n * lenient parsing can pre-filter their input.\n */\nexport async function fromString(\n  vault: Vault,\n  ndjson: string,\n  options: AsNDJSONImportOptions,\n): Promise<AsNDJSONImportPlan> {\n  vault.assertCanImport('plaintext', 'ndjson')\n  const policy: ImportPolicy = options.policy ?? 'merge'\n  const idKey = options.idKey ?? 'id'\n\n  const records: Record<string, unknown>[] = []\n  let lineNo = 0\n  for (const raw of ndjson.split('\\n')) {\n    lineNo++\n    const line = raw.trim()\n    if (!line) continue\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(line)\n    } catch (err) {\n      throw new Error(`as-ndjson.fromString: malformed JSON on line ${lineNo}: ${(err as Error).message}`)\n    }\n    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n      throw new Error(`as-ndjson.fromString: line ${lineNo} is not a JSON object`)\n    }\n    records.push(parsed as Record<string, unknown>)\n  }\n\n  const plan = await diffVault(vault, { [options.collection]: records }, {\n    collections: [options.collection],\n    idKey,\n  })\n\n  return {\n    plan,\n    policy,\n    async apply(): Promise<void> {\n      // Routes through the txStrategy seam — throws clearly when\n      // withTransactions() isn't opted in. Atomicity rolls back any\n      // partial writes if a put fails mid-batch.\n      await vault.noydb.transaction((tx) => {\n        const txVault = tx.vault(vault.name)\n        for (const entry of plan.added) {\n          txVault.collection(entry.collection).put(entry.id, entry.record)\n        }\n        if (policy !== 'insert-only') {\n          for (const entry of plan.modified) {\n            txVault.collection(entry.collection).put(entry.id, entry.record)\n          }\n        }\n        if (policy === 'replace') {\n          for (const entry of plan.deleted) {\n            txVault.collection(entry.collection).delete(entry.id)\n          }\n        }\n      })\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@noy-db/as-ndjson",
+  "version": "0.1.0-pre.10",
+  "description": "Newline-delimited JSON export for noy-db — streaming plaintext export suitable for data pipelines, warehouse ingestion, and jq pipelines. Gated by RFC #249 canExportPlaintext. Part of the @noy-db/as-* portable-artefact family (plaintext tier).",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/as-ndjson#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/as-ndjson"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.1.0-pre.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@noy-db/hub": "0.1.0-pre.10"
+  },
+  "keywords": [
+    "noy-db",
+    "as-ndjson",
+    "ndjson",
+    "streaming",
+    "export",
+    "plaintext",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}