@cbortech/cbor 0.27.0 → 0.27.2

package/README.ja.md

@@ -708,6 +708,79 @@ console.log(text);
 // DT'2026-05-06T00:00:00Z'
 ```
 
+### 項目ごとのオプション上書き
+
+`toJS()` の `itemOptions` は、各ノードが変換される直前にすべてのノードに対して呼ばれるため、
+ドキュメントの一部だけを他と異なる方法で変換できます。そのノードとその子孫に適用する
+オプションを部分的なオプションオブジェクトとして返すか、変更しない場合は `undefined` を
+返します。`ctx.path` は配列インデックスとマップキーからなる列でノードを識別し、
+ルートでは空になります。
+
+同じノードに対して複数回呼ばれることがあります —— `reviver` も併用している場合、配列や
+object-mode の map は各子要素を少なくとも2回変換します。1回は、先行する兄弟要素自身の
+`reviver` 呼び出しから見える値を構築するため、もう1回は実際に保持される値を計算するため
+です。このコールバックは `node`/`ctx` のみに依存する純粋関数として書き、呼ばれる回数には
+依存しないようにしてください。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN(
+  `{"date1": DT'2026-08-23T00:00:00Z', "date2": DT'2026-08-23T00:00:00Z'}`
+);
+
+const value = item.toJS({
+  stripTags: true,
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'date1'
+      ? { extensions: [CBOR.dt_as_Date] }
+      : undefined,
+});
+
+console.log(value);
+// { date1: Date(...), date2: 1787443200 }
+```
+
+`ToJSOptions` の `extensions` は `itemOptions` なしでも単体で機能し、ツリー全体を
+再解釈できます —— デフォルトの `dt` extension でパースされた値も、`toJS()` に
+`extensions` を渡すことで `dt_as_Date`（またはその逆）に変換し直せます。
+
+`ctx.options` には、そのノードにおいて現在有効なオプション —— ルートのオプションに
+祖先の `itemOptions` がすでに返した上書きをマージしたもの —— が渡されます。これにより、
+コールバックはオプションを丸ごと置き換えるのではなく、現在の値を土台にして組み立てる
+ことができます。
+
+```ts
+itemOptions: (_node, ctx) => ({
+  extensions: [...(ctx.options.extensions ?? []), CBOR.dt_as_Date],
+});
+```
+
+`toCDN()` にも同じ `itemOptions` オプションがあり、ドキュメントの一部だけを
+他と異なる方法でフォーマットできます。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN('{"raw": 255, "count": 255}');
+
+const text = item.toCDN({
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'raw'
+      ? { intFormat: 'hex' }
+      : undefined,
+});
+
+console.log(text);
+// {"raw":0xff,"count":255}
+```
+
+`toCDN()` には `reviver` に相当するものがないため、それを理由に複数回呼ばれる
+ことはありません —— ただし `toCDN()` 自体のレイアウト判定（`inlineLeafContainers`
+の1行収まるかの判定、あるいはタグ/app-sequence 値自身の複数語判定）が実際の
+出力より前にエントリを再描画してその答えを得ることがあるため、その場合には
+やはり複数回呼ばれ得ます。こちらも純粋な関数として書いてください。
+
 ## 文字列連結と不定長文字列
 
 draft-ietf-cbor-edn-literals-27(§3.5 / §3.6)の app-extension
@@ -1138,6 +1211,29 @@ const value = CBOR.parse('{"x": 12, "y": -3}', {
 検証オプションは `cddlValidationOptions` で渡せます。`cddl` は
 `new CBOR({ cddl: … })` のようにインスタンスのデフォルトにもできます。
 
+スキーマを指定すると、スキーマ自体が要求するタグは JavaScript 側で省略
+できます。`toJS()` は、prelude の `time = #6.1(number)` のような `#6.N(…)`
+型に一致したタグを外し、`fromJS()` はタグのない値にそれを補います。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const cddl = 'event = { t: time }';
+
+CBOR.parse(`{"t": DT'1969-07-21T02:56:16Z'}`, { cddl });
+// { t: -14159024 }（Tag.symbol のない素の number）
+
+CBOR.stringify({ t: -14159024 }, { cddl });
+// {"t":DT'1969-07-21T02:56:16Z'}
+```
+
+タグを外すのは `fromJS()` で復元できる場合だけです。タグなしの値もその
+位置で妥当な場合（`time / number`）や、スキーマがタグを要求しない場合
+（`any`）はタグを残します。推論は、値がそのままではスキーマに一致しない
+ときにだけ行います。すべてのタグを明示的に保持・要求するには
+`implicitTags: false`（`ToJSOptions` と `FromJSOptions` のオプション）を
+指定します。
+
 `CDDL.compile()` は `CddlSyntaxError` または `CddlSemanticError` を throw
 します。`{ strict: false }` を指定すると、意味上の問題を
 `schema.warnings` に収集できます。コンパイル済みスキーマは
@@ -1178,6 +1274,7 @@ CDDL コンパイラは `@cbortech/cbor/cddl`
 - CDN (CBOR-EDN)
   - [draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
   - [draft-ietf-cbor-edn-literals-27](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/27/)
+  - [draft-ietf-cbor-edn-e-ref-03](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-e-ref/03/)
 - CDDL
   - [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610)
   - [RFC 9682](https://www.rfc-editor.org/rfc/rfc9682)
@@ -1194,6 +1291,9 @@ CDDL コンパイラは `@cbortech/cbor/cddl`
   `#6.<type>` / `#7.<type>` head number に対応しています。コメントの `PCHAR`
   検証、単独 CR の改行、EOF で終わるコメントは、collected ABNF よりも意図的に
   寛容に受理します。
+- draft-ietf-cbor-edn-e-ref の `e'...'` application extension を試験的に
+  サポートしています(draft本文より狭いスコープで、整数リテラルに直接束縛された
+  名前のみ対応 — 文字列定数や、他の定数への別名参照は解決できません)。
 
 ## ライセンス
 

package/README.md

@@ -719,6 +719,81 @@ console.log(text);
 // DT'2026-05-06T00:00:00Z'
 ```
 
+### Per-item option overrides
+
+`itemOptions` on `toJS()` is called for every node before it is converted, so
+one part of a document can be converted differently from the rest. Return a
+partial options object to override options for that node and its descendants,
+or `undefined` to leave them unchanged. `ctx.path` identifies the node as a
+sequence of array indices and map keys, empty at the root.
+
+It can be called more than once for the same node — when a `reviver` is also
+present, arrays and object-mode maps convert each child at least twice: once
+to build a value visible to an earlier sibling's own `reviver` call, and once
+more for the value that's actually kept. Write it as a pure function of
+`node`/`ctx`, not relying on how many times it runs.
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN(
+  `{"date1": DT'2026-08-23T00:00:00Z', "date2": DT'2026-08-23T00:00:00Z'}`
+);
+
+const value = item.toJS({
+  stripTags: true,
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'date1'
+      ? { extensions: [CBOR.dt_as_Date] }
+      : undefined,
+});
+
+console.log(value);
+// { date1: Date(...), date2: 1787443200 }
+```
+
+`extensions` on `ToJSOptions` also works on its own, without `itemOptions`, to
+reinterpret an entire tree: a value parsed with the default `dt` extension can
+still be converted with `dt_as_Date` (or vice versa) by passing `extensions`
+directly to `toJS()`.
+
+`ctx.options` carries the options already in effect for the node — the root
+options merged with whatever an ancestor's `itemOptions` already returned —
+so a callback can build on the current value of an option instead of
+overriding it outright:
+
+```ts
+itemOptions: (_node, ctx) => ({
+  extensions: [...(ctx.options.extensions ?? []), CBOR.dt_as_Date],
+});
+```
+
+`toCDN()` takes the same `itemOptions` option, formatting one part of a
+document differently from the rest:
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN('{"raw": 255, "count": 255}');
+
+const text = item.toCDN({
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'raw'
+      ? { intFormat: 'hex' }
+      : undefined,
+});
+
+console.log(text);
+// {"raw":0xff,"count":255}
+```
+
+There is no `reviver` for `toCDN()`, so it can't be called more than once for
+that reason — but it can still be called more than once for a node that's
+also a `toCDN()` layout decision (`inlineLeafContainers`'s one-line collapse
+check, or a tag/app-sequence value's own multi-word check re-render an entry
+purely to answer that question before the real render). Write it as a pure
+function here too.
+
 ## String Concatenation and Indefinite-Length Strings
 
 The `t1` / `b1` / `ilbs` / `ilts` app-extensions from
@@ -1148,6 +1223,29 @@ Throwing methods such as `parse`, `decode`, and `encode` throw
 in `result.cddlErrors`. Pass validator options through `cddlValidationOptions`,
 or set `cddl` as an instance default with `new CBOR({ cddl: … })`.
 
+With a schema, tags the schema itself requires can be left implicit in
+JavaScript. `toJS()` drops a tag matched by a `#6.N(…)` type such as the
+prelude's `time = #6.1(number)`, and `fromJS()` adds it back to a value that
+lacks it:
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const cddl = 'event = { t: time }';
+
+CBOR.parse(`{"t": DT'1969-07-21T02:56:16Z'}`, { cddl });
+// { t: -14159024 } (a plain number, no Tag.symbol)
+
+CBOR.stringify({ t: -14159024 }, { cddl });
+// {"t":DT'1969-07-21T02:56:16Z'}
+```
+
+A tag is dropped only when `fromJS()` would restore it: it is kept where the
+untagged value is also valid on its own (`time / number`) or where the schema
+doesn't require it (`any`). Inference only runs when the value doesn't
+already match the schema. Pass `implicitTags: false` (a `ToJSOptions` and
+`FromJSOptions` option) to keep or require every tag explicitly.
+
 `CDDL.compile()` throws `CddlSyntaxError` or `CddlSemanticError`; use
 `{ strict: false }` to collect semantic issues in `schema.warnings` instead.
 Compiled schemas can be formatted with `schema.format()`. The subpath also
@@ -1188,6 +1286,7 @@ types).
 - CDN (CBOR-EDN)
   - [draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
   - [draft-ietf-cbor-edn-literals-27](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/27/)
+  - [draft-ietf-cbor-edn-e-ref-03](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-e-ref/03/)
 - CDDL
   - [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610)
   - [RFC 9682](https://www.rfc-editor.org/rfc/rfc9682)
@@ -1205,6 +1304,10 @@ Implementation notes:
   `#7.<type>` head numbers. Comment `PCHAR` validation, bare CR line endings,
   and comments ending at EOF are intentionally accepted more leniently than the
   collected ABNF.
+- Experimental support for draft-ietf-cbor-edn-e-ref's `e'...'` application
+  extension, limited to names bound directly to an integer literal (the
+  draft's own scope is broader) — a string constant, or an alias to another
+  named constant, doesn't resolve.
 
 ## License
 

package/dist/ast/CborAppSeqResult.d.ts

@@ -1,5 +1,5 @@
 import { ToCDNOptions, ToCBOROptions, ToJSOptions } from '../types';
-import { CborItem } from './CborItem';
+import { CborItem, Occurrence } from './CborItem';
 import { CborWriter } from '../cbor/encode';
 /**
  * Wraps a resolved app-sequence result and preserves the original EDN source
@@ -13,6 +13,39 @@ import { CborWriter } from '../cbor/encode';
  * lines also delegates to the inner item, since it cannot be re-emitted
  * without breaking the single-line guarantee.
  *
+ * When `toCDN()`'s `itemOptions` is configured (see `needsCdnItemDispatch`),
+ * the verbatim `ednSource` fast path alone can't be trusted: it was produced
+ * without ever visiting `this.inner`'s own descendants, so an override
+ * targeting one of them (e.g. one chunk of an `ilbs<<...>>`) would otherwise
+ * never even be offered the chance to apply. But merely *having* `itemOptions`
+ * configured must not by itself change the output — many callers set it
+ * without it ever matching anything in this particular subtree, and
+ * `itemOptions` returning `undefined` everywhere is documented to mean "no
+ * change" (see `CdnItemContext`). So this renders through the normal
+ * recursive path while tracking, via `CDN_OVERRIDE_TRACKER` (an out-of-band
+ * symbol key, *not* a wrapped `itemOptions` — wrapping it would make
+ * `ctx.options.itemOptions` a different function for every descendant here
+ * than everywhere else in the tree, observable even to a pure callback),
+ * whether any call in the subtree actually returned an override, and only
+ * swaps in that freshly rendered text when one did; otherwise the exact
+ * preserved `ednSource` is still returned.
+ *
+ * Each `_toCDN()` call installs its *own fresh* tracker box before
+ * recursing, rather than reusing whatever tracker it was handed — reusing
+ * one directly would let an override applied by some unrelated part of the
+ * tree that merely happens to share the same ambient `options` object (a
+ * later sibling reached through the same `itemOptions`, say) falsely mark
+ * *this* wrapper's own verbatim source as stale. But a genuinely *nested*
+ * app-sequence (e.g. a custom `wrap<<ilbs<<h'61'>>>>` extension wrapping an
+ * `ilbs<<...>>` result) must still have its own outer verbatim source
+ * abandoned when the inner wrapper's own tracked render found something to
+ * apply — an inner override changes what the outer source would need to
+ * embed too. So once this call's own local tracker comes back `applied`,
+ * that fact is additionally bubbled up to whichever ancestor tracker (if
+ * any) this call itself received via `options` — the exact wrapper this
+ * call is nested inside, never a sibling reached only through shared
+ * top-level `options`.
+ *
  * CBOR encoding and JS conversion always delegate to the inner item so the
  * wrapper is fully transparent for those operations.
  */
@@ -42,8 +75,8 @@ export declare class CborAppSeqResult extends CborItem {
      * already produced a `\n` in that string, which the caller's own
      * `s.includes('\n')` check picks up independently either way).
      */
-    _isMultiWordText(options: ToCDNOptions | undefined, strict?: boolean): boolean;
+    _isMultiWordText(options: ToCDNOptions | undefined, strict?: boolean, path?: readonly unknown[]): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
-    _toJS(options?: ToJSOptions): unknown;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: Occurrence): unknown;
 }

package/dist/ast/CborArray.d.ts

@@ -12,7 +12,7 @@ export declare class CborArray extends CborItem {
     });
     get _containsCdnContainer(): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
-    _toJS(options?: ToJSOptions): unknown;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: readonly unknown[]): unknown;
 }

package/dist/ast/CborByteString.d.ts

@@ -63,8 +63,8 @@ export declare class CborByteString extends CborItem {
      * needed here at all now — it's accepted purely for interface
      * consistency with the base class.
      */
-    _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean): boolean;
+    _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean, _path?: readonly unknown[]): boolean;
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, _depth: number, _path?: readonly unknown[]): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborEmbeddedCBOR.d.ts

@@ -21,7 +21,7 @@ export declare class CborEmbeddedCBOR extends CborItem {
     /** The raw concatenated CBOR bytes of all contained items. */
     private _content;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborFloat.d.ts

@@ -48,6 +48,6 @@ export declare class CborFloat extends CborItem {
         literalSource?: string;
     });
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, _depth: number, _path?: readonly unknown[]): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborIndefiniteByteString.d.ts

@@ -32,7 +32,7 @@ export declare class CborIndefiniteByteString extends CborItem {
      * was removed there too).
      */
     _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean): boolean;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborIndefiniteTextString.d.ts

@@ -24,7 +24,7 @@ export declare class CborIndefiniteTextString extends CborItem {
      * depend on it.
      */
     _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean): boolean;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;
 }