@cbortech/cbor 0.26.4 → 0.26.6

package/README.ja.md

@@ -6,13 +6,13 @@
 [![license](https://img.shields.io/npm/l/%40cbortech%2Fcbor)](./LICENSE)
 ![platform](https://img.shields.io/badge/platform-Node.js%20%7C%20Browser-blue)
 
-[CBOR](#準拠している仕様)、[CDN (CBOR-EDN)](#準拠している仕様)、JavaScript 値を相互変換するための TypeScript ライブラリです。
-
-![CBOR、CDN、JavaScript 値の関係図](./assets/cbor-cdn-js.png)
+[CBOR](#準拠している仕様)、[CDN (CBOR-EDN)](#準拠している仕様)、JavaScript 値の相互変換に加え、[CDDL](#準拠している仕様) スキーマのパース・整形・検証に対応する TypeScript ライブラリです。
 
 プレイグラウンドを **https://cbor.tech/cbor/** で公開しています。
 
-このパッケージは `CBOR` ファサードに加えて、extension の実装に必要な CBOR AST ノードクラス用の entrypoint を公開します。
+![CBOR、CDN、JavaScript 値の関係図](./assets/cbor-cdn-js.png)
+
+このパッケージは CBOR ファサードに加えて、tooling や extension 向けに CDN、CDDL、AST の各 entrypoint を公開します。
 低レベルのパーサー、エンコーダー内部は、ドキュメント上の公開 API には含めていません。
 
 ## インストール
@@ -72,6 +72,20 @@ console.log(value);
 // { hello: 'world', n: 42 }
 ```
 
+### CDDL で検証する
+
+CDDLスキーマをコンパイルし、CBOR バイト列、CDN テキスト、`CborItem` AST を検証できます。
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+const result = schema.validate('{"x": 12, "y": -3}');
+
+console.log(result.valid);
+// true
+```
+
 ### CBOR Sequence から JavaScript へ
 
 `decodeSeq` は連結された CBOR item を CBOR Sequence として読み取り、各 item を JavaScript 値として yield します。
@@ -324,7 +338,8 @@ syntax を扱う場合のためのものです。
 デフォルトでは、`CBOR.format()` は `+` による文字列連結を 1 つのリテラルに
 結合します。`preserveConcatenation` を指定すると、テキスト文字列・バイト文字列とも
 元の連結の区切りを保持します。`preserveByteString` を併用すると、バイト文字列の
-各パートの元の表記も保持されます。
+各パートの元の表記も保持されます。分割オプションと同様に `indent` で整形出力が
+有効な場合のみ効果があり、1 行出力では常に 1 つのリテラルに結合されます。
 
 分割オプションとの関係: 文字列の中身が CDN としてパースできる場合は `splitCdn` が
 `preserveConcatenation` より優先されます。`splitNewline` は共存し、保持した各パートに
@@ -336,14 +351,17 @@ import { CBOR } from '@cbortech/cbor';
 CBOR.format('"a" + "b"');
 // '"ab"'
 
-CBOR.format('"a" + "b"', { preserveConcatenation: true });
-// '"a" + "b"'
+CBOR.format('"a" + "b"', { indent: 2, preserveConcatenation: true });
+// "a" +
+//   "b"
 
 CBOR.format("h'68' + b64'aQ'", {
+  indent: 2,
   preserveConcatenation: true,
   preserveByteString: true,
 });
-// "h'68' + b64'aQ'"
+// h'68' +
+//   b64'aQ'
 ```
 
 ### CBOR / CDN / hex dump のバリデーション
@@ -861,12 +879,63 @@ const lenient = tokenizeLenient('[1, "ab');
 インスタンスで、`offset`・`line`・`column`、判明している場合は `endOffset` を
 保持します。
 
+## CDDL
+
+`@cbortech/cbor/cddl` サブパスには、CDDL のパーサ・コンパイラ・バリデータが
+入っています。CDDL は CBOR データ構造を記述するスキーマ言語です。
+コンパイル済みスキーマで、CBOR バイト列・CDN テキスト・`CborItem` AST を
+検証できます。
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+
+console.log(schema.validate('{"x": 12, "y": -3}').valid);
+// true
+```
+
+検証は throw せず結果オブジェクトを返し、失敗時は入力内のパスと入力・
+スキーマ双方のソース位置を報告します。既定では最初のルールを使い、`rule`
+で別の非 generic 型ルールを指定できます。このほか `features`、`maxDepth`、
+`maxSteps` を指定できます。
+
+[RFC 8610](https://www.rfc-editor.org/rfc/rfc8610) の全 control operator と、
+[RFC 9165](https://www.rfc-editor.org/rfc/rfc9165) の `.plus`、`.cat`、
+`.feature` を実装しています。`.feature` の許可名は `features` オプションで
+指定します。`.abnf` などの未対応演算子は `result.warnings` に報告され、
+制約なしで判定されます。
+
+メインの `CBOR` facade でも、`cddl` オプションにコンパイル済みスキーマ
+または CDDL ソーステキストを渡して検証できます。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const value = CBOR.parse('{"x": 12, "y": -3}', {
+  cddl: 'point = { x: int, y: int }',
+});
+// { x: 12, y: -3 }
+```
+
+`parse`・`decode`・`encode` などは不一致時に `CddlMismatchError` を throw
+します。`CBOR.validate()` は代わりに `result.cddlErrors` へ収集します。
+検証オプションは `cddlValidationOptions` で渡せます。`cddl` は
+`new CBOR({ cddl: … })` のようにインスタンスのデフォルトにもできます。
+
+`CDDL.compile()` は `CddlSyntaxError` または `CddlSemanticError` を throw
+します。`{ strict: false }` を指定すると、意味上の問題を
+`schema.warnings` に収集できます。コンパイル済みスキーマは
+`schema.format()` で整形できます。同じサブパスから `tokenize`、
+`tokenizeLenient`、`schema.ast`、`schema.rules` も利用できます。
+
 ## 公開 API
 
 ドキュメント化している公開 export は次のとおりです。
 
 - `CBOR`
 - `CdnSyntaxError`
+- `CddlMismatchError`(`cddl` オプションが throw。[CDDL](#cddl) 節を参照)
 
 `CBOR` ファサードからは次にもアクセスできます。
 
@@ -880,38 +949,34 @@ const lenient = tokenizeLenient('[1, "ab');
 (`tokenize`, `tokenizeLenient`, `Token`, `TokenType`, `EdnComment`)に、
 AST ノードクラスは `@cbortech/cbor/ast` にあります。
 
-## 準拠している仕様
-
-このライブラリは次の仕様を対象にしています。
-
-- [CBOR, RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
-- [Concise Diagnostic Notation (CDN), draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
+CDDL コンパイラは `@cbortech/cbor/cddl`
+(`CDDL`, `CddlSchema`, `CddlSyntaxError`, `CddlSemanticError`,
+`CddlMismatchError`, `tokenize`, `tokenizeLenient`, CDDL AST 型)に
+あります。
 
-draft -25 をベースに、
-[draft -26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/)
-の一部仕様も先行して取り込んでいます。
-
-- 文字列連結 extension `t1` / `b1`(§3.4)
-- 不定長文字列 extension `ilbs` / `ilts`(§3.5)
-- `float` extension のデフォルト有効化(§3.7)
-- draft-26 の raw string 規則(§2.5.4): 終端デリミタは開始デリミタと
-  同数のバッククォートに限られ、スペース除去規則がすべてのデリミタ長に
-  適用されます
-
-draft -26 で削除された `+` による文字列連結構文と、非推奨となった
-`(_ ...)` streamstring 構文は、引き続き受理します。CDN は Internet-Draft
-として策定中の仕様であり、今後も変更される可能性がある点に注意して
-ください(たとえば extension 名 `t1` / `b1` は暫定とされています)。
-
-CDN は、CBOR データを人間が読み書きしやすいテキストとして表現するための記法です。
-サンプル、テストベクター、デバッグ、fixture、設定ファイルに近い用途など、CBOR のバイト列をそのまま扱うと読みにくい場面で役立ちます。
-
-通常の配列、マップ、文字列、数値、真偽値、null は JSON に近い見た目で書けます。
-一方で、CBOR 固有の byte string、tag、simple value、不定長 item、文字列以外の map key、
-`dt'2026-05-06T00:00:00Z'` のような application literal も表現できます。
+## 準拠している仕様
 
-CDN は JSON / JSONC の上位互換なので、通常の JSON データやコメント付きの JSON 風データも、
-特別な変換なしに CDN としてパース・整形できます。
+- CBOR
+  - [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
+- 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-26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/)
+- CDDL
+  - [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610)
+  - [RFC 9682](https://www.rfc-editor.org/rfc/rfc9682)
+  - [RFC 9165](https://www.rfc-editor.org/rfc/rfc9165)
+
+補足:
+
+- CDN は draft-26 に準拠しつつ、draft-25 の `(_ ...)` streamstring 構文と
+  `+` による文字列連結構文も引き続きサポートしています。
+- CDDL は RFC 8610 のすべての control operator と、RFC 9165 の `.plus`、
+  `.cat`、`.feature` をサポートしています。
+- RFC 9682 の更新内容である文字列リテラル文法(`\u{...}` を含む)、構文上の
+  空データモデル(ルールなしのモデルはコンパイル時に意味エラー)、非リテラルの
+  `#6.<type>` / `#7.<type>` head number に対応しています。コメントの `PCHAR`
+  検証、単独 CR の改行、EOF で終わるコメントは、collected ABNF よりも意図的に
+  寛容に受理します。
 
 ## ライセンス
 

package/README.md

@@ -7,14 +7,15 @@
 ![platform](https://img.shields.io/badge/platform-Node.js%20%7C%20Browser-blue)
 
 TypeScript library for converting between [CBOR](#specifications),
-[CDN (CBOR-EDN)](#specifications), and JavaScript values.
-
-![Relationship between CBOR, CDN, and JavaScript values](./assets/cbor-cdn-js.png)
+[CDN (CBOR-EDN)](#specifications), and JavaScript values, plus parsing,
+formatting, and validation for [CDDL](#specifications) schemas.
 
 A live playground is available at **https://cbor.tech/cbor/**.
 
-This package exposes the `CBOR` facade plus a separate AST entrypoint for the
-CBOR node classes needed by extensions. Lower-level parser and encoder internals
+![Relationship between CBOR, CDN, and JavaScript values](./assets/cbor-cdn-js.png)
+
+This package exposes the CBOR facade plus separate CDN, CDDL, and AST
+entrypoints for tooling and extensions. Lower-level parser and encoder internals
 are not part of the documented public API.
 
 ## Install
@@ -75,6 +76,21 @@ console.log(value);
 // { hello: 'world', n: 42 }
 ```
 
+### Validate with CDDL
+
+Compile a CDDL schema and validate CBOR bytes, CDN text, or a `CborItem` AST
+against it:
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+const result = schema.validate('{"x": 12, "y": -3}');
+
+console.log(result.valid);
+// true
+```
+
 ### CBOR Sequence to JavaScript values
 
 `decodeSeq` reads concatenated CBOR items as a CBOR Sequence and yields each item as a JavaScript value.
@@ -328,7 +344,9 @@ handling legacy syntax.
 By default, `CBOR.format()` joins `+` string concatenation into a single
 literal. `preserveConcatenation` keeps the original part boundaries for both
 text strings and byte strings; add `preserveByteString` to also keep the
-original spelling of byte string parts.
+original spelling of byte string parts. Like the split options, it only
+takes effect when `indent` enables pretty-printing — single-line output
+always joins the parts.
 
 `preserveConcatenation` interacts with the split options: `splitCdn` takes
 precedence when the string content parses as CDN, while `splitNewline`
@@ -341,14 +359,17 @@ import { CBOR } from '@cbortech/cbor';
 CBOR.format('"a" + "b"');
 // '"ab"'
 
-CBOR.format('"a" + "b"', { preserveConcatenation: true });
-// '"a" + "b"'
+CBOR.format('"a" + "b"', { indent: 2, preserveConcatenation: true });
+// "a" +
+//   "b"
 
 CBOR.format("h'68' + b64'aQ'", {
+  indent: 2,
   preserveConcatenation: true,
   preserveByteString: true,
 });
-// "h'68' + b64'aQ'"
+// h'68' +
+//   b64'aQ'
 ```
 
 ### Validate CBOR / CDN / hex dump
@@ -869,12 +890,63 @@ Syntax errors thrown by `fromCDN`/`parse`/`tokenize` are `CdnSyntaxError`
 instances (a `SyntaxError` subclass, also exported from the main entry) and
 carry `offset`, `line`, `column`, and — where known — `endOffset`.
 
+## CDDL
+
+The `@cbortech/cbor/cddl` subpath contains a parser, compiler, and validator for
+CDDL, the schema language for describing CBOR data structures. A compiled schema
+validates CBOR bytes, CDN text, or a `CborItem` AST:
+
+```ts
+import { CDDL } from '@cbortech/cbor/cddl';
+
+const schema = CDDL.compile('point = { x: int, y: int }');
+
+console.log(schema.validate('{"x": 12, "y": -3}').valid);
+// true
+```
+
+Validation returns a result object rather than throwing. Failures include the
+instance path and source offsets for both the input and schema. Validation uses
+the first rule by default; pass `rule` to select another non-generic type rule.
+Options also include `features`, `maxDepth`, and `maxSteps`.
+
+All control operators from
+[RFC 8610](https://www.rfc-editor.org/rfc/rfc8610) are implemented, along with
+[RFC 9165](https://www.rfc-editor.org/rfc/rfc9165)'s `.plus`, `.cat`, and
+`.feature`. Enable `.feature` names with the `features` validation option.
+Unsupported operators such as `.abnf` are reported in `result.warnings` and
+matched without their constraint.
+
+The main `CBOR` facade also accepts a compiled schema or CDDL source text through
+the `cddl` option:
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const value = CBOR.parse('{"x": 12, "y": -3}', {
+  cddl: 'point = { x: int, y: int }',
+});
+// { x: 12, y: -3 }
+```
+
+Throwing methods such as `parse`, `decode`, and `encode` throw
+`CddlMismatchError` on a mismatch; `CBOR.validate()` instead collects failures
+in `result.cddlErrors`. Pass validator options through `cddlValidationOptions`,
+or set `cddl` as an instance default with `new CBOR({ cddl: … })`.
+
+`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
+exports `tokenize`, `tokenizeLenient`, and a typed rule AST through `schema.ast`
+and `schema.rules`.
+
 ## Public API
 
 The documented public exports are:
 
 - `CBOR`
 - `CdnSyntaxError`
+- `CddlMismatchError` (thrown by the `cddl` option; see [CDDL](#cddl))
 
 The `CBOR` facade also exposes:
 
@@ -888,41 +960,35 @@ Lower-level CDN tokenization lives in `@cbortech/cbor/cdn`
 (`tokenize`, `tokenizeLenient`, `Token`, `TokenType`, `EdnComment`),
 and AST node classes in `@cbortech/cbor/ast`.
 
-## Specifications
-
-This library targets:
-
-- [CBOR, RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
-- [Concise Diagnostic Notation (CDN), draft-ietf-cbor-edn-literals-25](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/25/)
+The CDDL compiler lives in `@cbortech/cbor/cddl`
+(`CDDL`, `CddlSchema`, `CddlSyntaxError`, `CddlSemanticError`,
+`CddlMismatchError`, `tokenize`, `tokenizeLenient`, and the CDDL AST
+types).
 
-On top of draft -25, this library already incorporates parts of
-[draft -26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/):
-
-- the `t1` / `b1` string-concatenation extensions (§3.4)
-- the `ilbs` / `ilts` indefinite-length string extensions (§3.5)
-- the `float` extension as a default extension (§3.7)
-- the draft-26 raw-string delimiter and trimming rules (§2.5.4): the closing
-  delimiter must have exactly as many backquotes as the opening one, and the
-  space-trimming rule applies to all delimiter lengths
-
-The legacy `+` string-concatenation syntax (removed in draft -26) and the
-`(_ ...)` streamstring syntax (deprecated in draft -26) are still accepted.
-Note that the CDN specification is still an Internet-Draft and may continue
-to change (for example, the extension names `t1` and `b1` are explicitly
-provisional).
-
-CDN is a human-readable text notation for CBOR data. It is useful for
-examples, test vectors, debugging, fixtures, and configuration-like files where
-raw CBOR bytes would be hard to read.
-
-It looks similar to JSON for ordinary arrays, maps, strings, numbers, booleans,
-and null values, but it can also represent CBOR-specific features such as byte
-strings, tags, simple values, indefinite-length items, non-string map keys, and
-application literals like `dt'2026-05-06T00:00:00Z'`.
+## Specifications
 
-CDN is a superset of JSON and JSONC, so ordinary JSON data and
-commented JSON-style data can be parsed and formatted as CDN without
-special handling.
+- CBOR
+  - [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949)
+- 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-26](https://datatracker.ietf.org/doc/draft-ietf-cbor-edn-literals/26/)
+- CDDL
+  - [RFC 8610](https://www.rfc-editor.org/rfc/rfc8610)
+  - [RFC 9682](https://www.rfc-editor.org/rfc/rfc9682)
+  - [RFC 9165](https://www.rfc-editor.org/rfc/rfc9165)
+
+Implementation notes:
+
+- CDN follows draft-26 while retaining draft-25's `(_ ...)` streamstring syntax
+  and `+` string-concatenation syntax.
+- CDDL implements every RFC 8610 control operator, plus RFC 9165's `.plus`,
+  `.cat`, and `.feature`.
+- The RFC 9682 updates are implemented: its string-literal grammar (including
+  `\u{...}`), empty data models at the syntax layer (a model with no rules is
+  still a semantic error when compiled), and non-literal `#6.<type>` /
+  `#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.
 
 ## License
 

package/dist/ast/CborAppSeqResult.d.ts

@@ -9,6 +9,9 @@ import { CborWriter } from '../cbor/encode';
  * stored source text verbatim. For `'always'` and `'never'`, it delegates to
  * the resolved item so the option is applied recursively to every data item;
  * preserving the source verbatim would leave nested indicators unchanged.
+ * In single-line output (no `indent`), a source spelling that spans multiple
+ * lines also delegates to the inner item, since it cannot be re-emitted
+ * without breaking the single-line guarantee.
  *
  * CBOR encoding and JS conversion always delegate to the inner item so the
  * wrapper is fully transparent for those operations.

package/dist/ast/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-DDJxbotH.cjs");exports.CborArray=e.C,exports.CborBigNint=e.v,exports.CborBigUint=e.y,exports.CborByteString=e.E,exports.CborEmbeddedCBOR=e.b,exports.CborFloat=e.O,exports.CborIndefiniteByteString=e.T,exports.CborIndefiniteTextString=e.w,exports.CborItem=e.j,exports.CborMap=e.S,exports.CborNint=e.k,exports.CborSimple=e.x,exports.CborTag=e.D,exports.CborTextString=e.g,exports.CborUint=e.A;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-BhMlCwYo.cjs");exports.CborArray=e.E,exports.CborBigNint=e.v,exports.CborBigUint=e.y,exports.CborByteString=e.k,exports.CborEmbeddedCBOR=e.C,exports.CborFloat=e.j,exports.CborIndefiniteByteString=e.O,exports.CborIndefiniteTextString=e.D,exports.CborItem=e.F,exports.CborMap=e.T,exports.CborNint=e.N,exports.CborSimple=e.w,exports.CborTag=e.A,exports.CborTextString=e.g,exports.CborUint=e.P;

package/dist/ast/index.js

@@ -1,2 +1,2 @@
-import { A as e, C as t, D as n, E as r, O as i, S as a, T as o, b as s, g as c, j as l, k as u, v as d, w as f, x as p, y as m } from "../mapEntries-hyNVtz5Z.js";
-export { t as CborArray, d as CborBigNint, m as CborBigUint, r as CborByteString, s as CborEmbeddedCBOR, i as CborFloat, o as CborIndefiniteByteString, f as CborIndefiniteTextString, l as CborItem, a as CborMap, u as CborNint, p as CborSimple, n as CborTag, c as CborTextString, e as CborUint };
+import { A as e, C as t, D as n, E as r, F as i, N as a, O as o, P as s, T as c, g as l, j as u, k as d, v as f, w as p, y as m } from "../mapEntries-Czxt-cmd.js";
+export { r as CborArray, f as CborBigNint, m as CborBigUint, d as CborByteString, t as CborEmbeddedCBOR, u as CborFloat, o as CborIndefiniteByteString, n as CborIndefiniteTextString, i as CborItem, c as CborMap, a as CborNint, p as CborSimple, e as CborTag, l as CborTextString, s as CborUint };

package/dist/cbor.d.ts

@@ -177,6 +177,14 @@ export declare class CBOR {
      * @example
      * // CDN text input
      * CBOR.validate('{"a": 1}', { type: 'cdn' });
+     *
+     * @example
+     * // Schema validation with a compiled CDDL schema
+     * import { CDDL } from '@cbortech/cbor/cddl';
+     * const schema = CDDL.compile('person = { name: tstr, ? age: uint }');
+     * const result = CBOR.validate('{"name": "kudo"}', { type: 'cdn', cddl: schema });
+     * result.valid;      // true
+     * result.cddlErrors; // []
      */
     static validate(input: ArrayBufferView | ArrayBufferLike | string, options?: ValidateOptions): ValidateResult;
     /**

package/dist/cddl/ast.d.ts

@@ -0,0 +1,196 @@
+/**
+ * CDDL AST node definitions.
+ *
+ * Unlike the CBOR side (class-based CborItem nodes), the CDDL AST is a plain
+ * discriminated-union structure: nodes are produced by the parser, consumed
+ * by the compiler/writer (and, in a later phase, the validator), and never
+ * carry behavior of their own.
+ *
+ * All nodes carry `start`/`end` character offsets into the parsed source so
+ * diagnostics and editor tooling can point at exact ranges.
+ */
+export interface CddlNodeBase {
+    /** Character offset of the first character of this node in the source. */
+    start: number;
+    /** Character offset just past the last character of this node. */
+    end: number;
+}
+/**
+ * rule = typename [genericparm] S assignt S type
+ *      / groupname [genericparm] S assigng S grpent
+ *
+ * Both forms are parsed into the same shape: `body` is a group entry, which
+ * subsumes a plain type (an entry with no occurrence and no member key).
+ * Whether a rule is used as a type or as a group is resolved semantically at
+ * validation time, not at parse time.
+ */
+export interface CddlRule extends CddlNodeBase {
+    kind: 'rule';
+    name: string;
+    /** Generic parameter names from `name<A, B> = …`, if any. */
+    generics?: string[];
+    /** '=' defines; '/=' extends a type choice; '//=' extends a group choice. */
+    assign: '=' | '/=' | '//=';
+    body: CddlGroupEntry;
+}
+/** type = type1 *(S "/" S type1) — always wrapped, even for one alternative. */
+export interface CddlType extends CddlNodeBase {
+    kind: 'type';
+    alternatives: CddlType1[];
+}
+/** type1 = type2 [S (rangeop / ctlop) S type2] */
+export interface CddlType1 extends CddlNodeBase {
+    kind: 'type1';
+    target: CddlType2;
+    /** Present when a range or control operator follows the target. */
+    op?: {
+        kind: 'range';
+        inclusive: boolean;
+    } | {
+        kind: 'ctl';
+        name: string;
+    };
+    /** The right-hand operand; present exactly when `op` is present. */
+    controller?: CddlType2;
+}
+export type CddlType2 = CddlValue | CddlRef | CddlParenType | CddlMapType | CddlArrayType | CddlUnwrap | CddlEnum | CddlTagged | CddlMajor | CddlAny;
+/** A literal value: number, text string, or byte string. */
+export type CddlValue = CddlNodeBase & {
+    kind: 'value';
+    raw: string;
+} & ({
+    type: 'int';
+    value: number | bigint;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'text';
+    value: string;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+    qualifier: '' | 'h' | 'b64';
+});
+/** typename [genericarg] — also used for groupname references. */
+export interface CddlRef extends CddlNodeBase {
+    kind: 'ref';
+    name: string;
+    genericArgs?: CddlType1[];
+}
+/** "(" S type S ")" */
+export interface CddlParenType extends CddlNodeBase {
+    kind: 'paren';
+    type: CddlType;
+}
+/** "{" S group S "}" */
+export interface CddlMapType extends CddlNodeBase {
+    kind: 'map';
+    group: CddlGroup;
+}
+/** "[" S group S "]" */
+export interface CddlArrayType extends CddlNodeBase {
+    kind: 'array';
+    group: CddlGroup;
+}
+/** "~" S typename [genericarg] */
+export interface CddlUnwrap extends CddlNodeBase {
+    kind: 'unwrap';
+    ref: CddlRef;
+}
+/** "&" S "(" S group S ")" / "&" S groupname [genericarg] */
+export interface CddlEnum extends CddlNodeBase {
+    kind: 'enum';
+    group: CddlGroup | CddlRef;
+}
+/**
+ * "#" "6" ["." head-number] "(" S type S ")" — a tagged item.
+ * `tag` is a literal tag number, a `<type>` head-number expression
+ * (RFC 9682 §3.2), or absent for `#6(…)` (any tag number).
+ */
+export interface CddlTagged extends CddlNodeBase {
+    kind: 'tagged';
+    tag?: bigint | CddlType;
+    item: CddlType;
+    /**
+     * Source text of the '#6[.head]' part (e.g. '#6.0x10') when the tag number
+     * is literal or absent; lets the formatter preserve the number base.
+     */
+    raw?: string;
+}
+/**
+ * "#" DIGIT ["." uint] and "#" "7" ["." head-number] — a major type,
+ * optionally constrained by additional information (or, for major 7, the
+ * simple value / float head-number, which may be a `<type>` expression).
+ */
+export interface CddlMajor extends CddlNodeBase {
+    kind: 'major';
+    major: number;
+    ai?: bigint | CddlType;
+    /**
+     * Source text of the '#N[.ai]' expression (e.g. '#7.0b11001') when the
+     * head-number is literal or absent; lets the formatter preserve the
+     * number base.
+     */
+    raw?: string;
+}
+/** "#" — any data item. */
+export interface CddlAny extends CddlNodeBase {
+    kind: 'any';
+}
+/** group = grpchoice *(S "//" S grpchoice); each choice is an entry list. */
+export interface CddlGroup extends CddlNodeBase {
+    kind: 'group';
+    choices: CddlGroupEntry[][];
+    /**
+     * True when the final entry is followed by a comma (optcom). Commas
+     * between entries are cosmetic and not recorded, but the trailing comma is
+     * syntactically significant: `(int,)` is a group, never a parenthesized
+     * type, so e.g. it cannot be the root of a data model.
+     */
+    trailingComma?: boolean;
+}
+export type CddlGroupEntry = CddlEntryValue | CddlEntryGroup;
+/** grpent = [occur S] [memberkey S] type — also covers bare group references. */
+export interface CddlEntryValue extends CddlNodeBase {
+    kind: 'entry';
+    occur?: CddlOccur;
+    memberKey?: CddlMemberKey;
+    value: CddlType;
+}
+/** grpent = [occur S] "(" S group S ")" — an inline parenthesized group. */
+export interface CddlEntryGroup extends CddlNodeBase {
+    kind: 'entry-group';
+    occur?: CddlOccur;
+    group: CddlGroup;
+}
+/**
+ * occur = [uint] "*" [uint] / "+" / "?"
+ * marker '*' covers `*`, `n*`, `*m`, and `n*m` via min/max.
+ */
+export interface CddlOccur extends CddlNodeBase {
+    kind: 'occur';
+    marker: '?' | '+' | '*';
+    min?: number;
+    max?: number;
+}
+/**
+ * memberkey = type1 S ["^" S] "=>"
+ *           / bareword S ":"
+ *           / value S ":"
+ *
+ * `cut` is true for the ':' forms (implicit cut, RFC 8610 §3.5.4) and for
+ * the explicit `^ =>` form.
+ */
+export type CddlMemberKey = CddlNodeBase & {
+    cut: boolean;
+} & ({
+    kind: 'type1';
+    key: CddlType1;
+} | {
+    kind: 'bareword';
+    key: string;
+} | {
+    kind: 'value';
+    key: CddlValue;
+});

package/dist/cddl/controls.d.ts

@@ -0,0 +1,28 @@
+import { CborItem } from '../ast/CborItem';
+import { CddlNodeBase, CddlType2, CddlValue } from './ast';
+type Path = readonly (string | number)[];
+/** Matching primitives provided by the validator (closed over env/ctx). */
+export interface ControlDeps {
+    matchType2(item: CborItem, t2: CddlType2, path: Path): boolean;
+    /** Like matchType2, but suppresses instance offsets in recorded errors —
+     *  the item was decoded out of an embedded byte string, so its offsets
+     *  are relative to the embedded bytes, not the outer document. */
+    matchEmbedded(item: CborItem, t2: CddlType2, path: Path): boolean;
+    resolveValue(t2: CddlType2): CddlValue | undefined;
+    /** Whether some integer ≥ min matches the type; undefined = unanalyzable. */
+    existsIntGE(t2: CddlType2, min: bigint): boolean | undefined;
+    matchesLiteral(item: CborItem, v: CddlValue): boolean;
+    fail(path: Path, item: CborItem | undefined, node: CddlNodeBase | undefined, message: string): false;
+    warnOnce(message: string, node?: CddlNodeBase): void;
+    features: ReadonlySet<string>;
+    uint(n: number | bigint): CborItem;
+}
+export type ControlHandler = (deps: ControlDeps, item: CborItem, target: CddlType2, controller: CddlType2, path: Path, node: CddlNodeBase) => boolean;
+/**
+ * The .feature controller is a feature name, or an array whose first
+ * element is the feature name and whose rest is detail (RFC 9165 §5) —
+ * either form may be parenthesized, e.g. `.feature (["x", "detail"])`.
+ */
+export declare const featureName: (deps: ControlDeps, controller: CddlType2) => string | undefined;
+export declare function getControl(name: string): ControlHandler | undefined;
+export {};