@cbortech/cbor 0.26.3 → 0.26.5

package/dist/types.d.ts

@@ -114,6 +114,20 @@ export interface ParseWarning {
      * fatal warnings as errors.
      */
     fatal?: boolean;
+    /**
+     * `true` when this entry is an informational hint (e.g. an app-string
+     * prefix matches a known optional extension that isn't registered) rather
+     * than a validity violation. Parsing is unaffected either way, but tooling
+     * that treats `onWarning` calls as failures (see `CBOR.validate()`) should
+     * not count these against validity.
+     */
+    hint?: boolean;
+    /**
+     * For a `fatal` warning built from a caught syntax error (see
+     * `CdnSyntaxError`), the original error object with its position fields
+     * intact. `CBOR.validate()` promotes this into `ValidateResult.error`.
+     */
+    cause?: Error;
 }
 export interface FromCBOROptions {
     /**
@@ -437,6 +451,11 @@ export interface ToCDNOptions {
      * - `number`: number of spaces
      * - `string`: literal indent string (e.g. `'\t'`)
      * - omit for single-line output
+     *
+     * 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.
      */
     indent?: number | string;
     /**
@@ -451,8 +470,9 @@ export interface ToCDNOptions {
      *   kept as-is.
      * - `false` / omitted: strip all comments from the output.
      *
-     * When enabled for containers, comment-bearing arrays/maps are emitted in
-     * multi-line form even if `indent` is omitted.
+     * Only effective when `indent` enables pretty-printing: single-line
+     * output strips all comments, since line comments (`#`, `//`) can only
+     * be terminated by a newline.
      *
      * @default false
      */
@@ -471,6 +491,10 @@ export interface ToCDNOptions {
      * 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.
+     *
      * @default false
      */
     preserveByteString?: boolean;
@@ -487,6 +511,9 @@ export interface ToCDNOptions {
      * Raw byte string forms (e.g. `` h`...` ``) are covered by
      * `preserveByteString`, 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
      */
     preserveRawString?: boolean;
@@ -542,7 +569,7 @@ export interface ToCDNOptions {
     floatFormat?: 'decimal' | 'hex';
     /**
      * Split long text strings using CDN string concatenation syntax (`"a" + "b"`).
-     * Only effective when `indent` is specified.
+     * Only effective when `indent` enables pretty-printing.
      *
      * - `'newline'`: split at newline characters
      * - `'cdn'`: split according to CDN structure when the string content
@@ -598,7 +625,8 @@ export interface ToCDNOptions {
      * text strings whose content parses as CDN, while `splitNewline` combines
      * with this option by further splitting the preserved parts at newline
      * characters. Has no effect on values that did not originate from a CDN
-     * concatenation.
+     * concatenation, and only takes effect when `indent` enables
+     * pretty-printing (single-line output joins the parts into one literal).
      *
      * @default false
      */
@@ -652,6 +680,71 @@ export interface CborComments {
     trailing?: CborComment[];
     dangling?: CborComment[];
 }
+/**
+ * Options for `CBOR.validate()`.
+ */
+export interface ValidateOptions {
+    /**
+     * Input format.
+     * - `'cbor'`: binary CBOR, decoded as a CBOR Sequence (RFC 8742).
+     * - `'cdn'`: CDN text, parsed as a CDN Sequence.
+     * - `'hex'`: annotated hex dump text, decoded as a CBOR Sequence.
+     * @default 'cbor'
+     */
+    type?: 'cbor' | 'cdn' | 'hex';
+    /**
+     * Extension plugins used while decoding/parsing.
+     * Mirrors `FromCBOROptions.extensions` / `FromCDNOptions.extensions`.
+     */
+    extensions?: CborExtension[];
+    /**
+     * Override the default set of bundled application-oriented extensions.
+     * Mirrors `FromCBOROptions.builtinExtensions`.
+     */
+    builtinExtensions?: CborExtension[] | false;
+    /**
+     * How to handle unrecognised application-extension identifiers.
+     * Only applies when `type` is `'cdn'`; mirrors `FromCDNOptions.unresolvedExtension`.
+     * @default 'cpa999'
+     */
+    unresolvedExtension?: 'cpa999' | 'error';
+}
+/**
+ * Result of `CBOR.validate()`.
+ */
+export interface ValidateResult {
+    /**
+     * `true` when every item decoded/parsed without error and without any
+     * warnings. `false` when the input was malformed (see `error`) or
+     * well-formed but in violation of a validity constraint (see `warnings`).
+     */
+    valid: boolean;
+    /** Number of items successfully decoded/parsed before any error. */
+    count: number;
+    /**
+     * Validity violations encountered while decoding/parsing in non-strict
+     * mode (recoverable — decoding continued after each one). Excludes
+     * informational hints (see `hints`) and the fatal CDN warning that
+     * `error` is built from, if any.
+     */
+    warnings: (DecodeWarning | ParseWarning)[];
+    /**
+     * Informational hints (`ParseWarning.hint`) encountered while parsing,
+     * e.g. an app-string prefix that matches a known optional extension which
+     * isn't registered. Hints never affect `valid`; they are collected here so
+     * tooling can still surface them.
+     */
+    hints: ParseWarning[];
+    /**
+     * Set when decoding/parsing failed outright: either it threw (e.g.
+     * truncated CBOR data), or — for CDN input — `fromCDNSeq()` abandoned the
+     * rest of the sequence after a hard syntax error (reported internally as a
+     * `fatal` warning, which `validate()` promotes to `error` rather than
+     * including in `warnings`). For a CDN syntax error this is the original
+     * `CdnSyntaxError`, position fields intact.
+     */
+    error?: Error;
+}
 /** `fromCBORSeq()` の options（`offset`/`allowTrailing` はジェネレータが管理するため除外）。 */
 export type FromCBORSeqOptions = Omit<FromCBOROptions, 'offset' | 'allowTrailing'>;
 /** `fromCDNSeq()` の options（`offset`/`allowTrailing` はジェネレータが管理するため除外）。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cbortech/cbor",
-  "version": "0.26.3",
+  "version": "0.26.5",
   "description": "Convert between CBOR, CDN (CBOR-EDN), and JavaScript values",
   "keywords": [
     "cbor",