@noy-db/as-json 0.6.0 → 0.7.0-pre.0

package/README.md

@@ -14,7 +14,7 @@ pnpm add @noy-db/hub @noy-db/as-json
 
 ## What it is
 
-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).
+Structured JSON plaintext export for noy-db — decrypts records and emits one JSON document per vault. Gated by `vault.assertCanExport('plaintext', …)` capability; writes an audit-ledger entry on every call. Part of the @noy-db/as-* portable-artefact family (plaintext tier).
 
 ## Status
 

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { VaultDiff, Vault } from '@noy-db/hub';
+import { ImportPolicy, ImportPlan, NoydbFormat } from '@noy-db/hub/as';
+export { ImportPolicy } from '@noy-db/hub/as';
+import { Vault } from '@noy-db/hub';
 
 /**
  * **@noy-db/as-json** — structured JSON plaintext export for noy-db.
@@ -6,7 +8,7 @@ import { VaultDiff, Vault } from '@noy-db/hub';
  * 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 +
+ * `assertCanExport('plaintext')` and paired with browser-download +
  * Node file-write helpers.
  *
  * **Scope.** Multi-collection per call (unlike `as-csv` which is
@@ -73,38 +75,49 @@ interface AsJSONWriteOptions extends AsJSONOptions {
  */
 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.
+ * Browser download — wraps `toString()` in a Blob and triggers the
+ * browser's save-as prompt. Requires a DOM — in Node, use `write()`.
  */
-declare function toString(vault: Vault, options?: AsJSONOptions): Promise<string>;
+/** Options a JSON format instance carries. Read concerns live on `vault.export`. */
+interface AsJSONFormatOptions {
+    /** Indent width, or `false` for compact. Default 2. */
+    readonly pretty?: number | boolean;
+    /** Keep `_noydb_*` metadata fields. Default false. */
+    readonly includeMeta?: boolean;
+}
 /**
- * Serialise the vault as a plain JS object. Useful for in-process
- * pipelines that want to post-process the data before writing.
+ * The JSON format — the `as-*` port instance.
+ *
+ * Unlike CSV and XML, JSON carries collection names in the payload, so
+ * `vault.import(asJson(), doc)` needs no `{ collection }`.
  */
-declare function toObject(vault: Vault, options?: AsJSONOptions): Promise<AsJSONDocument>;
+declare function asJson(options?: AsJSONFormatOptions): NoydbFormat<string>;
 /**
- * Browser download — wraps `toString()` in a Blob and triggers the
- * browser's save-as prompt. Requires a DOM — in Node, use `write()`.
+ * Serialise to a JSON string.
+ *
+ * Kept as a thin wrapper rather than removed, unlike as-csv/as-sql/as-xml: the
+ * gate, the read and the redaction still moved to hub, and this is now three
+ * lines over `vault.export`. Its sibling `toObject` is the reason — a document
+ * is not bytes, so `NoydbFormat<string>` cannot express it, and removing one
+ * while keeping the other would be a worse API than keeping both.
+ */
+declare function toString(vault: Vault, options?: AsJSONOptions): Promise<string>;
+/**
+ * Serialise to the parsed `{ collection: records[] }` document.
+ *
+ * The one export shape the format port does not carry, because a format
+ * produces bytes by definition. Round-tripping through `encode` keeps a single
+ * implementation rather than a second walk of the chunks.
  */
+declare function toObject(vault: Vault, options?: AsJSONOptions): Promise<AsJSONDocument>;
+/** Browser download. Hub gates, reads and redacts; this wraps the bytes. */
 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.
+ * Node file write. Not in hub because `hub-portable` forbids Node builtins
+ * there. The gate, the read and the redaction all moved.
  */
 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[];
@@ -119,22 +132,6 @@ interface AsJSONImportOptions {
  * 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>;
+type AsJSONImportPlan = ImportPlan;
 
-export { type AsJSONDocument, type AsJSONDownloadOptions, type AsJSONImportOptions, type AsJSONImportPlan, type AsJSONOptions, type AsJSONWriteOptions, type ImportPolicy, download, fromObject, fromString, toObject, toString, write };
+export { type AsJSONDocument, type AsJSONDownloadOptions, type AsJSONFormatOptions, type AsJSONImportOptions, type AsJSONImportPlan, type AsJSONOptions, type AsJSONWriteOptions, asJson, download, toObject, toString, write };

package/dist/index.js

@@ -1,55 +1,64 @@
 // src/index.ts
-import { applyListProjection } from "@noy-db/hub";
-import { diffVault } from "@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;
+function encodeJsonDoc(chunks, options) {
   const doc = {};
-  for await (const chunk of vault.exportStream({ granularity: "collection" })) {
-    if (allowlist && !allowlist.has(chunk.collection)) continue;
+  for (const chunk of chunks) {
     const bucket = doc[chunk.collection] ?? (doc[chunk.collection] = []);
-    const shouldRedact = options.redact !== void 0 && options.redact !== false;
-    const projectionOpts = shouldRedact && options.redact !== true ? { sensitivity: options.redact.sensitivity } : void 0;
-    const desc = shouldRedact ? vault.collection(chunk.collection).describe() : void 0;
     for (const record of chunk.records) {
-      let r = record;
-      if (shouldRedact && desc) {
-        r = applyListProjection(desc, r, projectionOpts);
-      }
-      if (options.includeMeta) {
-        bucket.push(r);
-      } else {
-        bucket.push(stripMeta(r));
-      }
+      const r = record;
+      bucket.push(options.includeMeta ? r : stripMeta(r));
     }
   }
   return doc;
 }
+function encodeJson(chunks, options) {
+  const indent = typeof options.pretty === "number" ? options.pretty : options.pretty === false ? 0 : 2;
+  return JSON.stringify(encodeJsonDoc(chunks, options), null, indent);
+}
+function asJson(options = {}) {
+  return {
+    id: "json",
+    extension: "json",
+    mimeType: "application/json;charset=utf-8",
+    tier: "plaintext",
+    encode: (chunks) => encodeJson(chunks, options),
+    decode: (input) => decodeJson(input)
+  };
+}
+function fmtOpts(o) {
+  return {
+    ...o.pretty !== void 0 ? { pretty: o.pretty } : {},
+    ...o.includeMeta !== void 0 ? { includeMeta: o.includeMeta } : {}
+  };
+}
+function readOpts(o) {
+  return {
+    ...o.collections ? { collections: o.collections } : {},
+    ...o.redact !== void 0 && o.redact !== false ? { redact: o.redact === true ? true : { sensitivity: o.redact.sensitivity } } : {}
+  };
+}
+async function toString(vault, options = {}) {
+  return vault.export(asJson(fmtOpts(options)), readOpts(options));
+}
+async function toObject(vault, options = {}) {
+  return JSON.parse(await toString(vault, options));
+}
 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 fmt = asJson(fmtOpts(options));
+  const json = await vault.export(fmt, readOpts(options));
+  const url = URL.createObjectURL(new Blob([json], { type: fmt.mimeType }));
   const a = document.createElement("a");
   a.href = url;
-  a.download = filename;
+  a.download = options.filename ?? `vault-export.${fmt.extension}`;
   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\\""'
-    );
+    throw new Error("as-json.write: acknowledgeRisks: true is required for on-disk plaintext output.");
   }
-  const json = await toString(vault, options);
+  const json = await vault.export(asJson(fmtOpts(options)), readOpts(options));
   const { writeFile } = await import("fs/promises");
-  await writeFile(path, json, "utf-8");
+  await writeFile(path, json, "utf8");
 }
 function stripMeta(record) {
   const out = {};
@@ -59,55 +68,24 @@ function stripMeta(record) {
   }
   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 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 = {}) {
+function decodeJson(json) {
   let parsed;
   try {
     parsed = JSON.parse(json);
   } catch (err) {
-    throw new Error(`as-json.fromString: input is not valid JSON (${err.message})`);
+    throw new Error(`as-json decode: 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}`
-    );
+    throw new Error("as-json decode: expected an object mapping { collection: records[] }");
   }
-  return fromObject(vault, parsed, options);
+  return Object.entries(parsed).map(([collection, records]) => ({
+    collection,
+    records: Array.isArray(records) ? records : []
+  }));
 }
 export {
+  asJson,
   download,
-  fromObject,
-  fromString,
   toObject,
   toString,
   write

package/dist/index.js.map

@@ -1 +1 @@
-{"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 { applyListProjection, type Vault, type CollectionDescription } 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  /**\n   * Apply the hub's `applyListProjection` read-projection before\n   * serialising records. `true` redacts only `classifiedFields` (mask /\n   * omit / rider, per the field's preset). The object form additionally\n   * redacts fields carrying a plain `fieldMeta` `sensitivity: 'pii' |\n   * 'secret'` tag, per `sensitivity: 'omit' | 'mask'`.\n   *\n   * Caveat: `describe()` reflects the declarations of *this session's*\n   * collection instance — redaction only takes effect when the\n   * collection was opened (this call or earlier in the session) with\n   * its `classifiedFields` / `fieldMeta` options. This is presentation-\n   * layer redaction; it never affects what's on disk. Sealed handles\n   * are unaffected either way — they always serialize as `'[sealed]'`,\n   * so ciphertext never leaks regardless of this option. Rider companion\n   * fields (e.g. `pan_last4`) remain visible as their own keys — they\n   * are safe write-time projections.\n   */\n  readonly redact?: boolean | { readonly sensitivity: 'omit' | 'mask' }\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    const shouldRedact = options.redact !== undefined && options.redact !== false\n    const projectionOpts = shouldRedact && options.redact !== true ? { sensitivity: options.redact.sensitivity } : undefined\n    const desc: CollectionDescription | undefined = shouldRedact ? vault.collection(chunk.collection).describe() : undefined\n    for (const record of chunk.records) {\n      let r = record as Record<string, unknown>\n      if (shouldRedact && desc) {\n        r = applyListProjection(desc, r, projectionOpts)\n      }\n      if (options.includeMeta) {\n        bucket.push(r)\n      } else {\n        bucket.push(stripMeta(r))\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 transactionsStrategy 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":";AAmBA,SAAS,2BAAmE;AAuJ5E,SAAS,iBAAiC;AAvF1C,eAAsB,SAAS,OAAc,UAAyB,CAAC,GAAoB;AACzF,QAAM,MAAM,MAAM,SAAS,OAAO,OAAO;AACzC,QAAM,SAAS,OAAO,QAAQ,WAAW,WACrC,QAAQ,SACR,QAAQ,WAAW,QACjB,IACA;AACN,SAAO,SAAS,IAAI,KAAK,UAAU,KAAK,MAAM,MAAM,IAAI,KAAK,UAAU,GAAG;AAC5E;AAMA,eAAsB,SAAS,OAAc,UAAyB,CAAC,GAA4B;AACjG,QAAM,gBAAgB,aAAa,MAAM;AAEzC,QAAM,YAAY,QAAQ,cAAc,IAAI,IAAI,QAAQ,WAAW,IAAI;AACvE,QAAM,MAAiD,CAAC;AACxD,mBAAiB,SAAS,MAAM,aAAa,EAAE,aAAa,aAAa,CAAC,GAAG;AAC3E,QAAI,aAAa,CAAC,UAAU,IAAI,MAAM,UAAU,EAAG;AACnD,UAAM,SAAS,IAAI,MAAM,UAAU,MAAM,IAAI,MAAM,UAAU,IAAI,CAAC;AAClE,UAAM,eAAe,QAAQ,WAAW,UAAa,QAAQ,WAAW;AACxE,UAAM,iBAAiB,gBAAgB,QAAQ,WAAW,OAAO,EAAE,aAAa,QAAQ,OAAO,YAAY,IAAI;AAC/G,UAAM,OAA0C,eAAe,MAAM,WAAW,MAAM,UAAU,EAAE,SAAS,IAAI;AAC/G,eAAW,UAAU,MAAM,SAAS;AAClC,UAAI,IAAI;AACR,UAAI,gBAAgB,MAAM;AACxB,YAAI,oBAAoB,MAAM,GAAG,cAAc;AAAA,MACjD;AACA,UAAI,QAAQ,aAAa;AACvB,eAAO,KAAK,CAAC;AAAA,MACf,OAAO;AACL,eAAO,KAAK,UAAU,CAAC,CAAC;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAMA,eAAsB,SAAS,OAAc,UAAiC,CAAC,GAAkB;AAC/F,QAAM,OAAO,MAAM,SAAS,OAAO,OAAO;AAC1C,QAAM,WAAW,QAAQ,YAAY;AACrC,QAAM,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,MAAM,iCAAiC,CAAC;AACxE,QAAM,MAAM,IAAI,gBAAgB,IAAI;AACpC,QAAM,IAAI,SAAS,cAAc,GAAG;AACpC,IAAE,OAAO;AACT,IAAE,WAAW;AACb,IAAE,MAAM;AACR,MAAI,gBAAgB,GAAG;AACzB;AAMA,eAAsB,MACpB,OACA,MACA,SACe;AACf,MAAI,QAAQ,qBAAqB,MAAM;AACrC,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,QAAM,OAAO,MAAM,SAAS,OAAO,OAAO;AAC1C,QAAM,EAAE,UAAU,IAAI,MAAM,OAAO,aAAkB;AACrD,QAAM,UAAU,MAAM,MAAM,OAAO;AACrC;AAEA,SAAS,UAAU,QAA0D;AAC3E,QAAM,MAA+B,CAAC;AACtC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,QAAQ,QAAQ,QAAQ,SAAS,QAAQ,SAAS,QAAQ,SAAS,QAAQ,WAAW,QAAQ,SAAU;AAC5G,QAAI,GAAG,IAAI;AAAA,EACb;AACA,SAAO;AACT;AA6CA,eAAsB,WACpB,OACA,KACA,UAA+B,CAAC,GACL;AAC3B,QAAM,gBAAgB,aAAa,MAAM;AACzC,QAAM,SAAuB,QAAQ,UAAU;AAC/C,QAAM,QAAQ,QAAQ,SAAS;AAI/B,QAAM,OAAO,MAAM,UAAU,OAAO,KAAsE;AAAA,IACxG,GAAI,QAAQ,cAAc,EAAE,aAAa,QAAQ,YAAY,IAAI,CAAC;AAAA,IAClE;AAAA,EACF,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,MAAM,QAAuB;AAQ3B,YAAM,MAAM,MAAM,YAAY,CAAC,OAAO;AACpC,cAAM,UAAU,GAAG,MAAM,MAAM,IAAI;AACnC,mBAAW,SAAS,KAAK,OAAO;AAC9B,kBAAQ,WAAW,MAAM,UAAU,EAAE,IAAI,MAAM,IAAI,MAAM,QAAQ,EAAE,QAAQ,cAAc,CAAC;AAAA,QAC5F;AACA,YAAI,WAAW,eAAe;AAC5B,qBAAW,SAAS,KAAK,UAAU;AACjC,oBAAQ,WAAW,MAAM,UAAU,EAAE,IAAI,MAAM,IAAI,MAAM,QAAQ,EAAE,QAAQ,cAAc,CAAC;AAAA,UAC5F;AAAA,QACF;AACA,YAAI,WAAW,WAAW;AACxB,qBAAW,SAAS,KAAK,SAAS;AAChC,oBAAQ,WAAW,MAAM,UAAU,EAAE,OAAO,MAAM,EAAE;AAAA,UACtD;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAOA,eAAsB,WACpB,OACA,MACA,UAA+B,CAAC,GACL;AAC3B,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM,IAAI;AAAA,EAC1B,SAAS,KAAK;AACZ,UAAM,IAAI,MAAM,gDAAiD,IAAc,OAAO,GAAG;AAAA,EAC3F;AACA,MAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GAAG;AAC1E,UAAM,IAAI;AAAA,MACR,mGACE,MAAM,QAAQ,MAAM,IAAI,UAAU,OAAO,MAC3C;AAAA,IACF;AAAA,EACF;AACA,SAAO,WAAW,OAAO,QAA0B,OAAO;AAC5D;","names":[]}
+{"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 * `assertCanExport('plaintext')` 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 {\n  ExportChunk,\n  NoydbFormat,\n  DecodedChunk,\n  FormatExportOptions,\n} from '@noy-db/hub/as'\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  /**\n   * Apply the hub's `applyListProjection` read-projection before\n   * serialising records. `true` redacts only `classifiedFields` (mask /\n   * omit / rider, per the field's preset). The object form additionally\n   * redacts fields carrying a plain `fieldMeta` `sensitivity: 'pii' |\n   * 'secret'` tag, per `sensitivity: 'omit' | 'mask'`.\n   *\n   * Caveat: `describe()` reflects the declarations of *this session's*\n   * collection instance — redaction only takes effect when the\n   * collection was opened (this call or earlier in the session) with\n   * its `classifiedFields` / `fieldMeta` options. This is presentation-\n   * layer redaction; it never affects what's on disk. Sealed handles\n   * are unaffected either way — they always serialize as `'[sealed]'`,\n   * so ciphertext never leaks regardless of this option. Rider companion\n   * fields (e.g. `pan_last4`) remain visible as their own keys — they\n   * are safe write-time projections.\n   */\n  readonly redact?: boolean | { readonly sensitivity: 'omit' | 'mask' }\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 */\n/**\n * The pure encoders — records in, JSON out. Already gated and already redacted\n * by hub; neither has a vault (ADR 0004).\n */\nfunction encodeJsonDoc(\n  chunks: readonly ExportChunk[],\n  options: AsJSONFormatOptions,\n): AsJSONDocument {\n  const doc: Record<string, Record<string, unknown>[]> = {}\n  for (const chunk of chunks) {\n    const bucket = doc[chunk.collection] ?? (doc[chunk.collection] = [])\n    for (const record of chunk.records) {\n      const r = record as Record<string, unknown>\n      bucket.push(options.includeMeta ? r : stripMeta(r))\n    }\n  }\n  return doc\n}\n\nfunction encodeJson(chunks: readonly ExportChunk[], options: AsJSONFormatOptions): string {\n  const indent = typeof options.pretty === 'number' ? options.pretty : options.pretty === false ? 0 : 2\n  return JSON.stringify(encodeJsonDoc(chunks, options), null, indent)\n}\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 */\n/** Options a JSON format instance carries. Read concerns live on `vault.export`. */\nexport interface AsJSONFormatOptions {\n  /** Indent width, or `false` for compact. Default 2. */\n  readonly pretty?: number | boolean\n  /** Keep `_noydb_*` metadata fields. Default false. */\n  readonly includeMeta?: boolean\n}\n\n/**\n * The JSON format — the `as-*` port instance.\n *\n * Unlike CSV and XML, JSON carries collection names in the payload, so\n * `vault.import(asJson(), doc)` needs no `{ collection }`.\n */\nexport function asJson(options: AsJSONFormatOptions = {}): NoydbFormat<string> {\n  return {\n    id: 'json',\n    extension: 'json',\n    mimeType: 'application/json;charset=utf-8',\n    tier: 'plaintext',\n    encode: (chunks) => encodeJson(chunks, options),\n    decode: (input) => decodeJson(input),\n  }\n}\n\n/** Only the keys actually set — `exactOptionalPropertyTypes` is on. */\nfunction fmtOpts(o: AsJSONOptions): AsJSONFormatOptions {\n  return {\n    ...(o.pretty !== undefined ? { pretty: o.pretty } : {}),\n    ...(o.includeMeta !== undefined ? { includeMeta: o.includeMeta } : {}),\n  }\n}\n\n\nfunction readOpts(o: AsJSONOptions): FormatExportOptions {\n  return {\n    ...(o.collections ? { collections: o.collections } : {}),\n    ...(o.redact !== undefined && o.redact !== false\n      ? { redact: o.redact === true ? true : { sensitivity: o.redact.sensitivity } }\n      : {}),\n  }\n}\n\n/**\n * Serialise to a JSON string.\n *\n * Kept as a thin wrapper rather than removed, unlike as-csv/as-sql/as-xml: the\n * gate, the read and the redaction still moved to hub, and this is now three\n * lines over `vault.export`. Its sibling `toObject` is the reason — a document\n * is not bytes, so `NoydbFormat<string>` cannot express it, and removing one\n * while keeping the other would be a worse API than keeping both.\n */\nexport async function toString(vault: Vault, options: AsJSONOptions = {}): Promise<string> {\n  return vault.export(asJson(fmtOpts(options)), readOpts(options))\n}\n\n/**\n * Serialise to the parsed `{ collection: records[] }` document.\n *\n * The one export shape the format port does not carry, because a format\n * produces bytes by definition. Round-tripping through `encode` keeps a single\n * implementation rather than a second walk of the chunks.\n */\nexport async function toObject(vault: Vault, options: AsJSONOptions = {}): Promise<AsJSONDocument> {\n  return JSON.parse(await toString(vault, options)) as AsJSONDocument\n}\n\n/** Browser download. Hub gates, reads and redacts; this wraps the bytes. */\nexport async function download(vault: Vault, options: AsJSONDownloadOptions = {}): Promise<void> {\n  const fmt = asJson(fmtOpts(options))\n  const json = await vault.export(fmt, readOpts(options))\n  const url = URL.createObjectURL(new Blob([json], { type: fmt.mimeType }))\n  const a = document.createElement('a')\n  a.href = url\n  a.download = options.filename ?? `vault-export.${fmt.extension}`\n  a.click()\n  URL.revokeObjectURL(url)\n}\n\n/**\n * Node file write. Not in hub because `hub-portable` forbids Node builtins\n * there. The gate, the read and the redaction all moved.\n */\nexport async function write(vault: Vault, path: string, options: AsJSONWriteOptions): Promise<void> {\n  if (options.acknowledgeRisks !== true) {\n    throw new Error('as-json.write: acknowledgeRisks: true is required for on-disk plaintext output.')\n  }\n  const json = await vault.export(asJson(fmtOpts(options)), readOpts(options))\n  const { writeFile } = await import('node:fs/promises')\n  await writeFile(path, json, 'utf8')\n}\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\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 */\n// Hub-owned as of 0.7 (ADR 0004). This line replaced a local declaration that\n// existed identically in six as-* packages, with nothing comparing them.\nimport type { ImportPolicy, ImportPlan } from '@noy-db/hub/as'\nexport type { ImportPolicy }\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 type AsJSONImportPlan = ImportPlan\n\n/**\n * Build an import plan from a parsed JSON document. Same shape\n * `as-json.toObject()` produces — `Record<collection, records[]>`.\n */\n/**\n * The pure decoder — JSON in, records out. No vault, no gate, no diff: hub\n * gates, plans against the live vault and owns `apply()`.\n */\nfunction decodeJson(json: string): readonly DecodedChunk[] {\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(json)\n  } catch (err) {\n    throw new Error(`as-json decode: input is not valid JSON (${(err as Error).message})`)\n  }\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    throw new Error('as-json decode: expected an object mapping { collection: records[] }')\n  }\n  // JSON DOES carry collection names — one key per collection — so unlike CSV\n  // and XML this format needs no `{ collection }` from the caller.\n  return Object.entries(parsed as Record<string, unknown>).map(([collection, records]) => ({\n    collection,\n    records: Array.isArray(records) ? records : [],\n  }))\n}\n\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@noy-db/as-json",
-  "version": "0.6.0",
-  "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).",
+  "version": "0.7.0-pre.0",
+  "description": "Structured JSON plaintext export for noy-db — decrypts records and emits one JSON document per vault. Gated by `vault.assertCanExport('plaintext', …)` 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>",
   "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/as-json#readme",
@@ -32,11 +32,11 @@
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "0.6.0"
+    "@noy-db/hub": "0.7.0-pre.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@noy-db/hub": "0.6.0"
+    "@noy-db/hub": "0.7.0-pre.0"
   },
   "keywords": [
     "noy-db",