@noy-db/as-json 0.2.0-pre.8 → 0.3.0-pre.1

package/README.md

@@ -26,7 +26,7 @@ See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup,
 
 - Source — [`packages/as-json`](https://github.com/vLannaAi/noy-db/tree/main/packages/as-json)
 - 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)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db-docs/blob/main/SPEC.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/as-json",
-  "version": "0.2.0-pre.8",
+  "version": "0.3.0-pre.1",
   "description": "Structured JSON plaintext export for noy-db — decrypts records and emits one JSON document per vault. Gated by RFC #249 canExportPlaintext capability; writes an audit-ledger entry on every call. Part of the @noy-db/as-* portable-artefact family (plaintext tier).",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -17,17 +17,10 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -36,14 +29,14 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "0.2.0-pre.8"
+    "@noy-db/hub": "0.3.0-pre.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@noy-db/hub": "0.2.0-pre.8"
+    "@noy-db/hub": "0.3.0-pre.1"
   },
   "keywords": [
     "noy-db",

package/dist/index.cjs

@@ -1,147 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  download: () => download,
-  fromObject: () => fromObject,
-  fromString: () => fromString,
-  toObject: () => toObject,
-  toString: () => toString,
-  write: () => write
-});
-module.exports = __toCommonJS(index_exports);
-var import_hub = require("@noy-db/hub");
-async function toString(vault, options = {}) {
-  const doc = await toObject(vault, options);
-  const indent = typeof options.pretty === "number" ? options.pretty : options.pretty === false ? 0 : 2;
-  return indent > 0 ? JSON.stringify(doc, null, indent) : JSON.stringify(doc);
-}
-async function toObject(vault, options = {}) {
-  vault.assertCanExport("plaintext", "json");
-  const allowlist = options.collections ? new Set(options.collections) : null;
-  const doc = {};
-  for await (const chunk of vault.exportStream({ granularity: "collection" })) {
-    if (allowlist && !allowlist.has(chunk.collection)) continue;
-    const bucket = doc[chunk.collection] ?? (doc[chunk.collection] = []);
-    for (const record of chunk.records) {
-      if (options.includeMeta) {
-        bucket.push(record);
-      } else {
-        bucket.push(stripMeta(record));
-      }
-    }
-  }
-  return doc;
-}
-async function download(vault, options = {}) {
-  const json = await toString(vault, options);
-  const filename = options.filename ?? "vault-export.json";
-  const blob = new Blob([json], { type: "application/json;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 write(vault, path, options) {
-  if (options.acknowledgeRisks !== true) {
-    throw new Error(
-      'as-json.write: acknowledgeRisks: true is required for on-disk plaintext output. See docs/patterns/as-exports.md \xA7"The three tiers of \\"plaintext out\\""'
-    );
-  }
-  const json = await toString(vault, options);
-  const { writeFile } = await import("fs/promises");
-  await writeFile(path, json, "utf-8");
-}
-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 fromObject(vault, doc, options = {}) {
-  vault.assertCanImport("plaintext", "json");
-  const policy = options.policy ?? "merge";
-  const idKey = options.idKey ?? "id";
-  const plan = await (0, import_hub.diffVault)(vault, doc, {
-    ...options.collections ? { collections: options.collections } : {},
-    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, { reason: "import:json" });
-        }
-        if (policy !== "insert-only") {
-          for (const entry of plan.modified) {
-            txVault.collection(entry.collection).put(entry.id, entry.record, { reason: "import:json" });
-          }
-        }
-        if (policy === "replace") {
-          for (const entry of plan.deleted) {
-            txVault.collection(entry.collection).delete(entry.id);
-          }
-        }
-      });
-    }
-  };
-}
-async function fromString(vault, json, options = {}) {
-  let parsed;
-  try {
-    parsed = JSON.parse(json);
-  } catch (err) {
-    throw new Error(`as-json.fromString: input is not valid JSON (${err.message})`);
-  }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(
-      `as-json.fromString: top-level value must be an object mapping collections \u2192 records[], got ${Array.isArray(parsed) ? "array" : typeof parsed}`
-    );
-  }
-  return fromObject(vault, parsed, options);
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  download,
-  fromObject,
-  fromString,
-  toObject,
-  toString,
-  write
-});
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/as-json** — structured JSON plaintext export for noy-db.\n *\n * Decrypts ACL-scoped records from a vault and emits one structured\n * JSON document grouping records by collection. Sibling to the core\n * `exportJSON()` helper — same shape, but gated behind\n * `canExportPlaintext` and paired with browser-download +\n * Node file-write helpers.\n *\n * **Scope.** Multi-collection per call (unlike `as-csv` which is\n * single-collection). Whole-vault by default; pass `collections` to\n * restrict.\n *\n * See `docs/patterns/as-exports.md` for the three-tier egress model\n * (Tier 1 in-memory → Tier 2 browser download → Tier 3 disk write).\n *\n * @packageDocumentation\n */\n\nimport type { Vault } from '@noy-db/hub'\n\nexport interface AsJSONOptions {\n  /**\n   * Collection allowlist. When omitted, every collection the caller\n   * can read is included. Collections not in the caller's ACL silently\n   * drop out even when listed here — ACL-scoping runs at the\n   * `exportStream` layer.\n   */\n  readonly collections?: readonly string[]\n\n  /**\n   * Pretty-print with indentation. Default `2` (2-space indent). Pass\n   * `0` or `false` for compact single-line output.\n   */\n  readonly pretty?: number | boolean\n\n  /**\n   * Include envelope metadata (`_v`, `_ts`, `_by`) alongside each\n   * record. Default `false` — stripped so the JSON matches the shape\n   * of the raw records the consumer originally put.\n   */\n  readonly includeMeta?: boolean\n}\n\nexport interface AsJSONDownloadOptions extends AsJSONOptions {\n  /** Filename offered to the browser. Default `'vault-export.json'`. */\n  readonly filename?: string\n}\n\nexport interface AsJSONWriteOptions extends AsJSONOptions {\n  /** Required to write plaintext JSON to disk — Tier 3 risk gate. */\n  readonly acknowledgeRisks: true\n}\n\n/**\n * Shape of the emitted document: one top-level key per collection,\n * each mapping to an array of record objects.\n */\nexport type AsJSONDocument = Record<string, readonly Record<string, unknown>[]>\n\n/**\n * Serialise the vault as a JSON string. Pure operation — no side\n * effects beyond the authorization check and audit ledger write.\n */\nexport async function toString(vault: Vault, options: AsJSONOptions = {}): Promise<string> {\n  const doc = await toObject(vault, options)\n  const indent = typeof options.pretty === 'number'\n    ? options.pretty\n    : options.pretty === false\n      ? 0\n      : 2\n  return indent > 0 ? JSON.stringify(doc, null, indent) : JSON.stringify(doc)\n}\n\n/**\n * Serialise the vault as a plain JS object. Useful for in-process\n * pipelines that want to post-process the data before writing.\n */\nexport async function toObject(vault: Vault, options: AsJSONOptions = {}): Promise<AsJSONDocument> {\n  vault.assertCanExport('plaintext', 'json')\n\n  const allowlist = options.collections ? new Set(options.collections) : null\n  const doc: Record<string, Record<string, unknown>[]> = {}\n  for await (const chunk of vault.exportStream({ granularity: 'collection' })) {\n    if (allowlist && !allowlist.has(chunk.collection)) continue\n    const bucket = doc[chunk.collection] ?? (doc[chunk.collection] = [])\n    for (const record of chunk.records) {\n      if (options.includeMeta) {\n        bucket.push(record as Record<string, unknown>)\n      } else {\n        bucket.push(stripMeta(record as Record<string, unknown>))\n      }\n    }\n  }\n  return doc\n}\n\n/**\n * Browser download — wraps `toString()` in a Blob and triggers the\n * browser's save-as prompt. Requires a DOM — in Node, use `write()`.\n */\nexport async function download(vault: Vault, options: AsJSONDownloadOptions = {}): Promise<void> {\n  const json = await toString(vault, options)\n  const filename = options.filename ?? 'vault-export.json'\n  const blob = new Blob([json], { type: 'application/json;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 file-write — persists the JSON to disk. Requires\n * `acknowledgeRisks: true` because plaintext outlives the process.\n */\nexport async function write(\n  vault: Vault,\n  path: string,\n  options: AsJSONWriteOptions,\n): Promise<void> {\n  if (options.acknowledgeRisks !== true) {\n    throw new Error(\n      'as-json.write: 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  const json = await toString(vault, options)\n  const { writeFile } = await import('node:fs/promises')\n  await writeFile(path, json, 'utf-8')\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\n/**\n * Reconciliation policy for `apply()`.\n *\n *   - `'merge'` (default) — insert + update, never delete. Records\n *     present in the live vault but absent from the file are left\n *     intact.\n *   - `'replace'` — full mirror. Records present in the live vault but\n *     absent from the file are deleted.\n *   - `'insert-only'` — only insert new records; skip both updates and\n *     deletes. Useful for append-only ledgers.\n */\nexport type ImportPolicy = 'merge' | 'replace' | 'insert-only'\n\nexport interface AsJSONImportOptions {\n  /** Restrict the diff + apply to a subset of collections. */\n  readonly collections?: readonly 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\n/**\n * Output of `fromString` / `fromObject` — preview the changes a JSON\n * import would apply, then commit them with `apply()`. Two-step shape\n * keeps the diff cheap and lets consumers render review-and-confirm\n * UIs without a separate dry-run mode.\n */\nexport interface AsJSONImportPlan {\n  readonly plan: VaultDiff\n  readonly policy: ImportPolicy\n  /** Apply every change in `plan` (filtered by `policy`) to the vault. */\n  apply(): Promise<void>\n}\n\n/**\n * Build an import plan from a parsed JSON document. Same shape\n * `as-json.toObject()` produces — `Record<collection, records[]>`.\n */\nexport async function fromObject(\n  vault: Vault,\n  doc: AsJSONDocument,\n  options: AsJSONImportOptions = {},\n): Promise<AsJSONImportPlan> {\n  vault.assertCanImport('plaintext', 'json')\n  const policy: ImportPolicy = options.policy ?? 'merge'\n  const idKey = options.idKey ?? 'id'\n\n  // Cast through unknown — diffVault is type-erased at the boundary\n  // and AsJSONDocument's per-record type is `Record<string, unknown>`.\n  const plan = await diffVault(vault, doc as unknown as Record<string, readonly Record<string, unknown>[]>, {\n    ...(options.collections ? { collections: options.collections } : {}),\n    idKey,\n  })\n\n  return {\n    plan,\n    policy,\n    async apply(): Promise<void> {\n      // Add and modify go through collection.put which runs the normal\n      // permissions check + envelope encryption + ledger write.\n      // Delete only runs under the 'replace' policy.\n      // Wrapped via vault.noydb.transaction so a partial failure rolls\n      // back every executed put. Routes through the txStrategy seam —\n      // throws a clear error pointing at withTransactions() when the\n      // strategy is not opted in.\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, { reason: 'import:json' })\n        }\n        if (policy !== 'insert-only') {\n          for (const entry of plan.modified) {\n            txVault.collection(entry.collection).put(entry.id, entry.record, { reason: 'import:json' })\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\n/**\n * Build an import plan from a JSON string — parse, then dispatch to\n * `fromObject`. Convenience for the canonical \"load my exported file\"\n * workflow.\n */\nexport async function fromString(\n  vault: Vault,\n  json: string,\n  options: AsJSONImportOptions = {},\n): Promise<AsJSONImportPlan> {\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(json)\n  } catch (err) {\n    throw new Error(`as-json.fromString: input is not valid JSON (${(err as Error).message})`)\n  }\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    throw new Error(\n      `as-json.fromString: top-level value must be an object mapping collections → records[], got ${\n        Array.isArray(parsed) ? 'array' : typeof parsed\n      }`,\n    )\n  }\n  return fromObject(vault, parsed as AsJSONDocument, options)\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -1,120 +0,0 @@
-import { VaultDiff, Vault } from '@noy-db/hub';
-
-/**
- * **@noy-db/as-json** — structured JSON plaintext export for noy-db.
- *
- * Decrypts ACL-scoped records from a vault and emits one structured
- * JSON document grouping records by collection. Sibling to the core
- * `exportJSON()` helper — same shape, but gated behind
- * `canExportPlaintext` and paired with browser-download +
- * Node file-write helpers.
- *
- * **Scope.** Multi-collection per call (unlike `as-csv` which is
- * single-collection). Whole-vault by default; pass `collections` to
- * restrict.
- *
- * See `docs/patterns/as-exports.md` for the three-tier egress model
- * (Tier 1 in-memory → Tier 2 browser download → Tier 3 disk write).
- *
- * @packageDocumentation
- */
-
-interface AsJSONOptions {
-    /**
-     * Collection allowlist. When omitted, every collection the caller
-     * can read is included. Collections not in the caller's ACL silently
-     * drop out even when listed here — ACL-scoping runs at the
-     * `exportStream` layer.
-     */
-    readonly collections?: readonly string[];
-    /**
-     * Pretty-print with indentation. Default `2` (2-space indent). Pass
-     * `0` or `false` for compact single-line output.
-     */
-    readonly pretty?: number | boolean;
-    /**
-     * Include envelope metadata (`_v`, `_ts`, `_by`) alongside each
-     * record. Default `false` — stripped so the JSON matches the shape
-     * of the raw records the consumer originally put.
-     */
-    readonly includeMeta?: boolean;
-}
-interface AsJSONDownloadOptions extends AsJSONOptions {
-    /** Filename offered to the browser. Default `'vault-export.json'`. */
-    readonly filename?: string;
-}
-interface AsJSONWriteOptions extends AsJSONOptions {
-    /** Required to write plaintext JSON to disk — Tier 3 risk gate. */
-    readonly acknowledgeRisks: true;
-}
-/**
- * Shape of the emitted document: one top-level key per collection,
- * each mapping to an array of record objects.
- */
-type AsJSONDocument = Record<string, readonly Record<string, unknown>[]>;
-/**
- * Serialise the vault as a JSON string. Pure operation — no side
- * effects beyond the authorization check and audit ledger write.
- */
-declare function toString(vault: Vault, options?: AsJSONOptions): Promise<string>;
-/**
- * Serialise the vault as a plain JS object. Useful for in-process
- * pipelines that want to post-process the data before writing.
- */
-declare function toObject(vault: Vault, options?: AsJSONOptions): Promise<AsJSONDocument>;
-/**
- * Browser download — wraps `toString()` in a Blob and triggers the
- * browser's save-as prompt. Requires a DOM — in Node, use `write()`.
- */
-declare function download(vault: Vault, options?: AsJSONDownloadOptions): Promise<void>;
-/**
- * Node file-write — persists the JSON to disk. Requires
- * `acknowledgeRisks: true` because plaintext outlives the process.
- */
-declare function write(vault: Vault, path: string, options: AsJSONWriteOptions): Promise<void>;
-
-/**
- * Reconciliation policy for `apply()`.
- *
- *   - `'merge'` (default) — insert + update, never delete. Records
- *     present in the live vault but absent from the file are left
- *     intact.
- *   - `'replace'` — full mirror. Records present in the live vault but
- *     absent from the file are deleted.
- *   - `'insert-only'` — only insert new records; skip both updates and
- *     deletes. Useful for append-only ledgers.
- */
-type ImportPolicy = 'merge' | 'replace' | 'insert-only';
-interface AsJSONImportOptions {
-    /** Restrict the diff + apply to a subset of collections. */
-    readonly collections?: readonly string[];
-    /** Field on each record that carries its id. Default `'id'`. */
-    readonly idKey?: string;
-    /** Reconciliation policy. Default `'merge'`. */
-    readonly policy?: ImportPolicy;
-}
-/**
- * Output of `fromString` / `fromObject` — preview the changes a JSON
- * import would apply, then commit them with `apply()`. Two-step shape
- * keeps the diff cheap and lets consumers render review-and-confirm
- * UIs without a separate dry-run mode.
- */
-interface AsJSONImportPlan {
-    readonly plan: VaultDiff;
-    readonly policy: ImportPolicy;
-    /** Apply every change in `plan` (filtered by `policy`) to the vault. */
-    apply(): Promise<void>;
-}
-/**
- * Build an import plan from a parsed JSON document. Same shape
- * `as-json.toObject()` produces — `Record<collection, records[]>`.
- */
-declare function fromObject(vault: Vault, doc: AsJSONDocument, options?: AsJSONImportOptions): Promise<AsJSONImportPlan>;
-/**
- * Build an import plan from a JSON string — parse, then dispatch to
- * `fromObject`. Convenience for the canonical "load my exported file"
- * workflow.
- */
-declare function fromString(vault: Vault, json: string, options?: AsJSONImportOptions): Promise<AsJSONImportPlan>;
-
-export { type AsJSONDocument, type AsJSONDownloadOptions, type AsJSONImportOptions, type AsJSONImportPlan, type AsJSONOptions, type AsJSONWriteOptions, type ImportPolicy, download, fromObject, fromString, toObject, toString, write };