@cbortech/cbor 0.26.5 → 0.26.7

package/dist/types.d.ts

@@ -1,4 +1,7 @@
 import { CborExtension } from './extensions/types';
+import { CddlSchema } from './cddl/schema';
+import { ValidateOptions as CddlValidateOptions } from './cddl/validator';
+import { CddlValidationError, CddlValidationWarning } from './cddl/errors';
 /**
  * Shared option types and plugin interfaces.
  */
@@ -216,6 +219,29 @@ export interface FromCBOROptions {
      * @default false
      */
     silent?: boolean;
+    /**
+     * CDDL schema to validate decoded items against: either a compiled schema
+     * (`CDDL.compile()` from `@cbortech/cbor/cddl`) or CDDL source text.
+     * Source text is compiled on first use with default compile options and
+     * cached, so passing the same string repeatedly does not recompile; pass a
+     * compiled schema to control `CompileOptions` yourself. Invalid CDDL text
+     * throws `CddlSyntaxError` / `CddlSemanticError` at the call site.
+     *
+     * Each decoded item is validated after decoding, against the schema's
+     * root rule by default (or `cddlValidationOptions.rule`, if set); a
+     * mismatch throws {@link CddlMismatchError}. Sequence entry points
+     * (`fromCBORSeq`, `decodeSeq`, …) validate each item of the sequence
+     * individually against that same rule. `CBOR.validate()` collects
+     * mismatches into `ValidateResult.cddlErrors` instead of throwing.
+     */
+    cddl?: CddlSchema | string;
+    /**
+     * Options forwarded to the CDDL validator when `cddl` is supplied
+     * (`features` for the `.feature` control operator, `maxDepth`,
+     * `maxSteps`, and `rule` to validate against a rule other than the
+     * schema's root). Ignored without `cddl`.
+     */
+    cddlValidationOptions?: CddlValidateOptions;
 }
 /**
  * Options for parsing an annotated hex dump.
@@ -253,6 +279,16 @@ export interface FromHexDumpOptions {
      * @default false
      */
     silent?: boolean;
+    /**
+     * Compiled CDDL schema to validate decoded items against.
+     * Mirrors `FromCBOROptions.cddl`.
+     */
+    cddl?: CddlSchema | string;
+    /**
+     * Options forwarded to the CDDL validator.
+     * Mirrors `FromCBOROptions.cddlValidationOptions`.
+     */
+    cddlValidationOptions?: CddlValidateOptions;
 }
 export interface FromCDNOptions {
     /**
@@ -353,6 +389,17 @@ export interface FromCDNOptions {
      * @default false
      */
     preserveComments?: boolean | 'c-style' | 'cdn-style';
+    /**
+     * Shorthand for `ToCDNOptions.preserveAll`, so a single option enables
+     * round-tripping through both `fromCDN()` and `toCDN()` (as
+     * `CBOR.format()` does internally). On the parse side, this only implies
+     * `preserveComments: true` (comments must be captured while parsing to be
+     * re-emittable); the other `preserve*` behaviors are always captured by
+     * the parser and only need to be turned on for `toCDN()`.
+     *
+     * @default false
+     */
+    preserveAll?: boolean;
     /**
      * Controls how CDN/EDN validity violations are handled.
      *
@@ -386,6 +433,16 @@ export interface FromCDNOptions {
      * @default false
      */
     silent?: boolean;
+    /**
+     * Compiled CDDL schema to validate parsed items against.
+     * Mirrors `FromCBOROptions.cddl`.
+     */
+    cddl?: CddlSchema | string;
+    /**
+     * Options forwarded to the CDDL validator.
+     * Mirrors `FromCBOROptions.cddlValidationOptions`.
+     */
+    cddlValidationOptions?: CddlValidateOptions;
 }
 /**
  * Options for parsing Concise Diagnostic Notation (CDN).
@@ -444,6 +501,16 @@ export interface FromJSOptions {
      * @default false
      */
     undefinedOmits?: boolean;
+    /**
+     * Compiled CDDL schema to validate the constructed item against, before
+     * encoding/serialization. Mirrors `FromCBOROptions.cddl`.
+     */
+    cddl?: CddlSchema | string;
+    /**
+     * Options forwarded to the CDDL validator.
+     * Mirrors `FromCBOROptions.cddlValidationOptions`.
+     */
+    cddlValidationOptions?: CddlValidateOptions;
 }
 export interface ToCDNOptions {
     /**
@@ -455,9 +522,34 @@ export interface ToCDNOptions {
      * Like `JSON.stringify`, `0` and `''` are equivalent to omitting the
      * option: the output is a single line. Single-line output is guaranteed
      * to contain no newlines; layout-dependent options (`preserveComments`,
-     * `splitCdn`, `splitNewline`, `preserveConcatenation`) are ignored.
+     * `preserveBlankLines`, `splitCdn`, `splitNewline`, `preserveConcatenation`)
+     * are ignored.
      */
     indent?: number | string;
+    /**
+     * Master switch that turns on every `preserve*` option below at once —
+     * `preserveComments`, `preserveByteString`, `preserveRawString`,
+     * `preserveTextString`, `preserveConcatenation`, `preserveNumberFormat`,
+     * `preserveAppSequence`, and `preserveBlankLines` — for reformatting CDN
+     * text (e.g. on save in an editor) with minimal changes: only
+     * whitespace/indentation, plus anything an explicitly-set individual
+     * option overrides.
+     *
+     * An option explicitly set to a value (including `false`) is left as-is;
+     * `preserveAll` only fills in the ones left `undefined`. So
+     * `{ preserveAll: true, preserveNumberFormat: false }` preserves
+     * everything except number literal spelling.
+     *
+     * When parsing via `CBOR.fromCDN()` separately from `toCDN()` (rather
+     * than through `CBOR.format()`, which passes the same options to both),
+     * also pass `preserveAll` (or `preserveComments`) to `FromCDNOptions` so
+     * comments are captured in the first place — see
+     * `FromCDNOptions.preserveAll`. Bignums are unaffected by
+     * `preserveNumberFormat` even under `preserveAll`; see that option.
+     *
+     * @default false
+     */
+    preserveAll?: boolean;
     /**
      * Emit comments previously captured by `FromCDNOptions.preserveComments`.
      *
@@ -477,23 +569,48 @@ export interface ToCDNOptions {
      * @default false
      */
     preserveComments?: boolean | 'c-style' | 'cdn-style';
+    /**
+     * Re-emit a blank line above an array/map entry (or indefinite-length
+     * string chunk) that had one before it anywhere in the parsed CDN source,
+     * so paragraph-like groupings of entries survive a reformat. At most one
+     * blank line is ever emitted per gap, regardless of how many blank lines
+     * were originally there.
+     *
+     * Detection is based purely on entry source positions — it does not
+     * require `preserveComments` and is unaffected by whether comments are
+     * emitted.
+     *
+     * Only effective when `indent` enables pretty-printing. A container with
+     * a preserved blank line is always emitted one-entry-per-line, the same
+     * as a container with preserved comments (see `inlineLeafContainers`).
+     *
+     * @default false
+     */
+    preserveBlankLines?: boolean;
     /**
      * Re-emit byte string literals parsed from CDN using their original source
      * text when available.
      *
      * This preserves the spelling and interior layout of non-concatenated
      * `h'...'`, `b64'...'`, `b32'...'`, `h32'...'`, raw-backtick byte strings,
-     * and single-quoted byte strings, including comments inside those literals.
-     * Byte strings produced by `+` concatenation are normalised as usual;
-     * combine with `preserveConcatenation` to keep both the part boundaries
-     * and each part's spelling.
+     * and single-quoted byte strings — including a `h'xx...yy'`-family elided
+     * literal (§4.2), whose spelling is kept independently of
+     * `preserveConcatenation` when it has no `+` of its own (see that
+     * option). Byte strings produced by `+` concatenation are normalised as
+     * usual; combine with `preserveConcatenation` to keep both the part
+     * boundaries and each part's spelling.
+     *
+     * A comment inside the literal is stripped unless `preserveComments` is
+     * also set — `preserveByteString` alone preserves everything about the
+     * literal's spelling *except* its comments, the same as an unpreserved
+     * literal (re-derived from the decoded value) never has comments either.
      *
      * When enabled, this takes precedence over `bstrEncoding` and `sqstr` for
      * byte strings that carry original EDN source text.
      *
      * In single-line output (no `indent`), an original spelling that spans
-     * multiple lines (e.g. a byte string literal with interior line comments)
-     * falls back to normal serialization; single-line spellings are kept.
+     * multiple lines — after any comment is stripped — falls back to normal
+     * serialization; single-line spellings are kept.
      *
      * @default false
      */
@@ -517,6 +634,48 @@ export interface ToCDNOptions {
      * @default false
      */
     preserveRawString?: boolean;
+    /**
+     * Re-emit double-quoted text strings (`"..."`) using their original CDN
+     * source spelling — escape sequences (`é` vs. the literal character),
+     * quoting choices, etc. — instead of re-escaping them from the decoded
+     * string value.
+     *
+     * Applies to non-concatenated double-quoted literals only; a string
+     * reached via `+` concatenation is normalised as usual regardless of this
+     * option. Preserved strings are emitted verbatim: they are never
+     * re-indented or split by `splitCdn` / `splitNewline`.
+     *
+     * Raw backtick literals (`` `...` ``) are covered by `preserveRawString`,
+     * not this option.
+     *
+     * In single-line output (no `indent`), a spelling that spans multiple
+     * lines falls back to normal escaping; single-line spellings are kept.
+     *
+     * @default false
+     */
+    preserveTextString?: boolean;
+    /**
+     * Re-emit integer and floating-point literals using their original CDN
+     * source spelling — base (`0xff` / `0o377` / `0b101` / decimal), digit
+     * spelling, decimal point / exponent form, and encoding-indicator suffix
+     * (e.g. `1.5_1`) — instead of normalising them via `intFormat` /
+     * `floatFormat` and recomputed encoding indicators.
+     *
+     * Takes precedence over `intFormat` and `floatFormat` for literals parsed
+     * from CDN text. Values that did not originate from CDN text (e.g. built
+     * via `CBOR.from()` or decoded from CBOR bytes) always fall back to normal
+     * formatting, since there is no original spelling to preserve. Bignums
+     * (integers outside the uint64/int64 range) are unaffected and always
+     * render as plain decimal.
+     *
+     * Combine with `preserveByteString`, `preserveRawString`,
+     * `preserveConcatenation`, and `preserveComments` to reformat CDN text
+     * (e.g. whitespace/indentation only) with minimal changes to the rest of
+     * the source.
+     *
+     * @default false
+     */
+    preserveNumberFormat?: boolean;
     /**
      * Whether to emit commas between array/map elements.
      * - `'comma'`: emit commas (`[1, 2, 3]`)
@@ -551,6 +710,37 @@ export interface ToCDNOptions {
      * @default true
      */
     appStrings?: boolean;
+    /**
+     * For built-in extensions that support application-string notation
+     * (`prefix'...'` or `` prefix`...` ``), application-sequence notation
+     * (`prefix<<...>>`), and/or a raw tag literal (`N(...)`), re-emit a value
+     * using its exact original spelling instead of normalizing it to the
+     * regenerated `prefix'...'` form.
+     *
+     * By default, an extension like `dt`/`DT` or `ip`/`IP` regenerates its
+     * notation from the resolved value on every call — so
+     * `` DT`1969-07-21T02:56:16Z` ``, `DT<<'1969-07-21T02:56:16Z'>>`, and even
+     * the raw tag form `1(1749772800)` all become
+     * `DT'2025-06-13T00:00:00Z'`-style `prefix'...'` notation, even though all
+     * of these denote the same value. `preserveAppSequence` keeps the
+     * original spelling instead — whichever quoting (`'...'` vs `` `...` ``),
+     * bracketing (`<<...>>`), or raw tag form was used. Has no effect when
+     * `appStrings` is `false` (raw tag notation is used either way regardless
+     * of the original spelling), or on values not parsed from one of these
+     * forms.
+     *
+     * In single-line output (no `indent`), a spelling that spans multiple
+     * lines falls back to normal (regenerated) notation; single-line
+     * spellings are kept.
+     *
+     * An explicit `preserveComments` setting is still applied to comments
+     * inside a preserved application-sequence spelling: marker styles are
+     * normalised without changing the notation family, and `false` removes
+     * the comments while retaining the surrounding source spelling.
+     *
+     * @default false
+     */
+    preserveAppSequence?: boolean;
     /**
      * Numeric format for integer values in CDN output.
      * - `'decimal'`: standard decimal notation (e.g. `42`, `-14159024`)
@@ -628,6 +818,19 @@ export interface ToCDNOptions {
      * concatenation, and only takes effect when `indent` enables
      * pretty-printing (single-line output joins the parts into one literal).
      *
+     * Also applies within an elision (`...`, §4.2 of
+     * draft-ietf-cbor-edn-literals-25): a `+`-joined fragment on either side of
+     * an ellipsis keeps its own part boundaries too (e.g. `'test' +
+     * h'1234...abcd' + ...` stays exactly as written instead of merging
+     * `'test'` into the byte fragment before it), and byte-string elision
+     * keeps the `h'xx' + ... + h'yy'` spelling instead of the default compact
+     * `h'xx...yy'` literal. Unlike the text/byte-string case above, this
+     * applies regardless of `indent`, and the parts stay on one line even
+     * under `indent` (elision is always single-line): a `+` boundary inside an
+     * ellipsis is never a lossless merge — the elided middle can't be "joined
+     * in" — so there's no indent-dependent fallback to prefer, and no reason
+     * to reflow it.
+     *
      * @default false
      */
     preserveConcatenation?: boolean;
@@ -638,6 +841,12 @@ export interface ToCDNOptions {
      * `{"a": 1}`, `(_ "a", "b")`). Nested leaf containers still collapse
      * individually: `[[1, 2], [3, 4]]` renders with one inner array per line.
      *
+     * `<<...>>` (CBOR Sequence Literal / embedded CBOR) is the one exception:
+     * since it's a flat sequence of encoded items rather than a
+     * nested-structure display, an entry that is itself an array/map still
+     * inlines there as long as its own rendering fits on one line — e.g.
+     * `<<{1: -7}>>` stays on one line, even though `[{1: -7}]` would not.
+     *
      * Containers with preserved comments are always emitted in multi-line
      * form. Has no effect when `indent` is omitted.
      *
@@ -674,6 +883,15 @@ export interface CborComment {
     end: number;
     line: number;
     col: number;
+    /**
+     * `true` when this is a `leading` comment that ends on the same source
+     * line as the node it's attached to — e.g. `/ protected / << ... >>` in an
+     * RFC 9052-style annotated array, as opposed to a comment on its own line
+     * above the value. `toCDN()` renders these as an inline prefix on the
+     * value's own line instead of a separate line above it. `undefined` for
+     * `trailing`/`dangling` comments, where it doesn't apply.
+     */
+    sameLine?: boolean;
 }
 export interface CborComments {
     leading?: CborComment[];
@@ -708,6 +926,27 @@ export interface ValidateOptions {
      * @default 'cpa999'
      */
     unresolvedExtension?: 'cpa999' | 'error';
+    /**
+     * CDDL schema to validate each decoded/parsed item against: either a
+     * compiled schema (`CDDL.compile()` from `@cbortech/cbor/cddl`) or CDDL
+     * source text (compiled on first use and cached; mirrors
+     * `FromCBOROptions.cddl`).
+     *
+     * Unlike the throwing entry points, `CBOR.validate()` does not throw on a
+     * mismatch: failures are collected into `ValidateResult.cddlErrors` (and
+     * validator observations into `ValidateResult.cddlWarnings`), and any
+     * mismatch makes `valid` `false`. Each item of a sequence is validated
+     * individually against the schema's root rule by default (or
+     * `cddlValidationOptions.rule`, if set). Note that invalid CDDL source
+     * text itself still throws (`CddlSyntaxError` / `CddlSemanticError`): the
+     * schema is part of the call, not the data being validated.
+     */
+    cddl?: CddlSchema | string;
+    /**
+     * Options forwarded to the CDDL validator.
+     * Mirrors `FromCBOROptions.cddlValidationOptions`.
+     */
+    cddlValidationOptions?: CddlValidateOptions;
 }
 /**
  * Result of `CBOR.validate()`.
@@ -744,6 +983,18 @@ export interface ValidateResult {
      * `CdnSyntaxError`, position fields intact.
      */
     error?: Error;
+    /**
+     * CDDL validation failures, collected per decoded item. Only present when
+     * `ValidateOptions.cddl` was supplied (empty array when every item
+     * matched). Any entry makes `valid` `false`.
+     */
+    cddlErrors?: CddlValidationError[];
+    /**
+     * Non-fatal CDDL validator observations (e.g. unsupported control
+     * operators whose constraints were skipped). Only present when
+     * `ValidateOptions.cddl` was supplied. Never affects `valid`.
+     */
+    cddlWarnings?: CddlValidationWarning[];
 }
 /** `fromCBORSeq()` の options（`offset`/`allowTrailing` はジェネレータが管理するため除外）。 */
 export type FromCBORSeqOptions = Omit<FromCBOROptions, 'offset' | 'allowTrailing'>;

package/dist/utils/base64.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Decode base64 text (classic or URL-safe alphabet, padding optional) into
+ * bytes, with strict RFC 4648 validation.
+ *
+ * Used by the CDN parser (b64'…' literals, §5.3.4) and the CDDL tokenizer
+ * (b64'…' byte strings, RFC 8610 §3.1).
+ *
+ * Recoverable deviations (padding-count mismatches, non-zero trailing bits)
+ * are reported through `onRecoverableError` when provided; otherwise they
+ * throw a plain SyntaxError, which callers wrap with position information.
+ */
+export declare function base64ToBytes(b64: string, onRecoverableError?: (msg: string) => void): Uint8Array;

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@cbortech/cbor",
-  "version": "0.26.5",
-  "description": "Convert between CBOR, CDN (CBOR-EDN), and JavaScript values",
+  "version": "0.26.7",
+  "description": "Convert between CBOR, CDN (CBOR-EDN), and JavaScript values with CDDL validation",
   "keywords": [
     "cbor",
     "cdn",
+    "cddl",
+    "cddl-validation",
+    "rfc8610",
     "cbor-edn",
     "diagnostic-notation",
     "json",
@@ -60,6 +63,16 @@
         "types": "./dist/cdn/index.d.ts",
         "default": "./dist/cdn/index.cjs"
       }
+    },
+    "./cddl": {
+      "import": {
+        "types": "./dist/cddl/index.d.ts",
+        "default": "./dist/cddl/index.js"
+      },
+      "require": {
+        "types": "./dist/cddl/index.d.ts",
+        "default": "./dist/cddl/index.cjs"
+      }
     }
   },
   "files": [
@@ -81,11 +94,13 @@
     "start": "node dist/index.js",
     "dev": "npm run build && npm start",
     "clean": "node -e \"['dist','coverage'].forEach(d=>require('fs').rmSync(d,{recursive:true,force:true}))\"",
-    "test": "vitest run --exclude src/cdn/edn-test-vectors.test.ts --exclude src/cdn/edn-abnf-vectors.test.ts",
+    "test": "vitest run --exclude src/cdn/edn-test-vectors.test.ts --exclude src/cdn/edn-abnf-vectors.test.ts --exclude src/cddl/cddl-corpus.test.ts --exclude src/cddl/cddl-validation-vectors.test.ts --exclude site/src/playground.browser.test.ts",
     "test:exports": "npm run build && node scripts/check-package-exports.mjs",
-    "test:node": "vitest run --exclude src/cdn/edn-test-vectors.test.ts --exclude src/cdn/edn-abnf-vectors.test.ts",
+    "test:node": "vitest run --exclude src/cdn/edn-test-vectors.test.ts --exclude src/cdn/edn-abnf-vectors.test.ts --exclude src/cddl/cddl-corpus.test.ts --exclude src/cddl/cddl-validation-vectors.test.ts --exclude site/src/playground.browser.test.ts",
     "test:edn-vectors": "vitest run src/cdn/edn-test-vectors.test.ts",
     "test:edn-abnf": "vitest run src/cdn/edn-abnf-vectors.test.ts",
+    "test:cddl-corpus": "vitest run src/cddl/cddl-corpus.test.ts",
+    "test:cddl-vectors": "vitest run src/cddl/cddl-validation-vectors.test.ts",
     "test:chromium": "cross-env BROWSER=chromium vitest run --config vitest.browser.config.ts",
     "test:firefox": "cross-env BROWSER=firefox vitest run --config vitest.browser.config.ts",
     "test:webkit": "cross-env BROWSER=webkit vitest run --config vitest.browser.config.ts",
@@ -99,9 +114,11 @@
     "site:clean": "npm run --workspace site clean",
     "site:dev": "npm run build && npm run --workspace site dev",
     "site:build": "npm run build && npm run --workspace site build",
-    "site:preview": "npm run site:build && npm run --workspace site preview"
+    "site:preview": "npm run site:build && npm run --workspace site preview",
+    "site:test": "npm run build && npm run --workspace site test"
   },
   "devDependencies": {
+    "@cbortech/hash-extension": "^0.2.3",
     "@types/node": "^24.13.3",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
@@ -109,9 +126,9 @@
     "@vitest/ui": "^4.1.10",
     "cross-env": "^10.1.0",
     "playwright": "^1.61.1",
-    "prettier": "^3.9.5",
+    "prettier": "^3.9.6",
     "typescript": "^5.9.3",
-    "vite": "^8.1.4",
+    "vite": "^8.1.5",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.1.10"
   }