@svta/cml-structured-field-values 0.19.0 → 0.21.0

package/README.md

@@ -0,0 +1,25 @@
+# @svta/cml-structured-field-values
+
+RFC8941 Structured Field Values implementation.
+
+## Installation
+
+```bash
+npm i @svta/cml-structured-field-values
+```
+
+## Usage
+
+```typescript
+import { encodeSfDict } from "@svta/cml-structured-field-values";
+
+const dict = encodeSfDict({
+	a: 1,
+	b: false,
+	c: "x",
+	d: Symbol.for("y"),
+	e: new Uint8Array([1, 2, 3]),
+});
+
+assert(dict === `a=1, b=?0, c="x", d=y, e=:AQID:`);
+```

package/dist/index.d.ts

@@ -1,22 +1,393 @@
+//#region src/SfDecodeOptions.d.ts
 /**
- * A collection of tools for working with structured fields.
- *
- * @packageDocumentation
- */
-export * from './decodeSfDict.js';
-export * from './decodeSfItem.js';
-export * from './decodeSfList.js';
-export * from './encodeSfDict.js';
-export * from './encodeSfItem.js';
-export * from './encodeSfList.js';
-export type * from './SfBareItem.js';
-export type * from './SfDecodeOptions.js';
-export type * from './SfDictionary.js';
-export type * from './SfEncodeOptions.js';
-export type * from './SfInnerList.js';
-export * from './SfItem.js';
-export type * from './SfMember.js';
-export type * from './SfParameters.js';
-export * from './SfToken.js';
-export * from './utils/symbolToStr.js';
+* Options for decoding Structured Field values
+*
+*
+* @beta
+*/
+type SfDecodeOptions = {
+  /**
+  * Use JS Symbol to represent token values
+  */
+  useSymbol?: boolean;
+};
+//#endregion
+//#region src/SfToken.d.ts
+/**
+* A class to represent structured field tokens when `Symbol` is not available.
+*
+*
+* @beta
+*/
+declare class SfToken {
+  description: string;
+  constructor(description: string);
+}
+//#endregion
+//#region src/SfBareItem.d.ts
+/**
+* A type to represent structured field bare items.
+*
+*
+* @beta
+*/
+type SfBareItem = string | Uint8Array | boolean | number | symbol | Date | SfToken;
+//#endregion
+//#region src/SfParameters.d.ts
+/**
+* Structured Field Parameters
+*
+*
+* @beta
+*/
+type SfParameters = Record<string, any>;
+//#endregion
+//#region src/SfItem.d.ts
+/**
+* Structured Field Item
+*
+*
+* @beta
+*/
+declare class SfItem {
+  value: SfBareItem;
+  params?: SfParameters;
+  constructor(value: any, params?: SfParameters);
+}
+//#endregion
+//#region src/SfInnerList.d.ts
+/**
+* Structured Field Inner List
+*
+*
+* @beta
+*/
+type SfInnerList = {
+  value: SfItem[] | SfBareItem[];
+  params: SfParameters;
+};
+//#endregion
+//#region src/SfMember.d.ts
+/**
+* A member of a structured field.
+*
+*
+* @beta
+*/
+type SfMember = SfItem | SfInnerList | SfBareItem;
+//#endregion
+//#region src/SfDictionary.d.ts
+/**
+* A dictionary of structured field members.
+*
+*
+* @beta
+*/
+type SfDictionary = Record<string, SfMember> | Map<string, SfMember>;
+//#endregion
+//#region src/decodeSfDict.d.ts
+/**
+* Decode a structured field string into a structured field dictionary
+*
+* @param input - The structured field string to decode
+* @returns The structured field dictionary
+*
+*
+* @beta
+*/
+declare function decodeSfDict(input: string, options?: SfDecodeOptions): SfDictionary;
+//#endregion
+//#region src/decodeSfItem.d.ts
+/**
+* Decode a structured field string into a structured field item
+*
+* @param input - The structured field string to decode
+* @returns The structured field item
+*
+*
+* @beta
+*/
+declare function decodeSfItem(input: string, options?: SfDecodeOptions): SfItem;
+//#endregion
+//#region src/decodeSfList.d.ts
+/**
+* Decode a structured field string into a structured field list
+*
+* @param input - The structured field string to decode
+* @returns The structured field list
+*
+*
+* @beta
+*/
+declare function decodeSfList(input: string, options?: SfDecodeOptions): SfMember[];
+//#endregion
+//#region src/SfEncodeOptions.d.ts
+/**
+* Options for encoding a structured field.
+*
+*
+* @beta
+*/
+type SfEncodeOptions = {
+  /**
+  * Include whitespace in the output.
+  */
+  whitespace?: boolean;
+};
+//#endregion
+//#region src/encodeSfDict.d.ts
+/**
+* Encode an object into a structured field dictionary
+*
+* @param value - The structured field dictionary to encode
+* @param options - Encoding options
+*
+* @returns The structured field string
+*
+*
+* @beta
+*/
+declare function encodeSfDict(value: Record<string, any> | Map<string, any>, options?: SfEncodeOptions): string;
+//#endregion
+//#region src/encodeSfItem.d.ts
+/**
+* Encode a structured field item to a string
+*
+* @param value - The structured field item to encode
+*
+* @returns The structured field string
+*
+*
+* @beta
+*/
+declare function encodeSfItem(value: SfItem): string;
+/**
+* Encode a structured field value to a string with optional parameters.
+*
+* @param value - The structured field value to encode
+* @param params - The structured field parameters
+*
+* @returns The structured field string
+*
+* @beta
+*/
+declare function encodeSfItem(value: SfBareItem, params?: SfParameters): string;
+//#endregion
+//#region src/encodeSfList.d.ts
+/**
+* Encode a list into a structured field dictionary
+*
+* @param value - The structured field list to encode
+* @param options - Encoding options
+*
+* @returns The structured field string
+*
+*
+* @beta
+*/
+declare function encodeSfList(value: SfMember[], options?: SfEncodeOptions): string;
+//#endregion
+//#region src/utils/symbolToStr.d.ts
+/**
+* Converts a symbol to a string.
+*
+* @param symbol - The symbol to convert.
+*
+* @returns The string representation of the symbol.
+*
+*
+* @beta
+*/
+declare function symbolToStr(symbol: symbol | SfToken): string;
+//#endregion
+//#region src/parse/ParsedValue.d.ts
+/**
+* @internal
+*/
+type ParsedValue<T> = {
+  value: T;
+  src: string;
+};
+//#endregion
+//#region src/parse/parseBareItem.d.ts
+/**
+* @internal
+*/
+declare function parseBareItem(src: string, options?: SfDecodeOptions): ParsedValue<SfBareItem>;
+//#endregion
+//#region src/parse/parseBoolean.d.ts
+/**
+* @internal
+*/
+declare function parseBoolean(src: string): ParsedValue<boolean>;
+//#endregion
+//#region src/parse/parseByteSequence.d.ts
+/**
+* @internal
+*/
+declare function parseByteSequence(src: string): ParsedValue<Uint8Array>;
+//#endregion
+//#region src/parse/parseDate.d.ts
+/**
+* @internal
+*/
+declare function parseDate(src: string): ParsedValue<Date>;
+//#endregion
+//#region src/parse/parseDict.d.ts
+/**
+* @internal
+*/
+declare function parseDict(src: string, options?: SfDecodeOptions): ParsedValue<SfDictionary>;
+//#endregion
+//#region src/parse/parseError.d.ts
+/**
+* @internal
+*/
+declare function parseError(src: any, type: string, cause?: any): Error;
+//#endregion
+//#region src/parse/parseInnerList.d.ts
+/**
+* @internal
+*/
+declare function parseInnerList(src: string, options?: SfDecodeOptions): ParsedValue<SfInnerList>;
+//#endregion
+//#region src/parse/parseIntegerOrDecimal.d.ts
+/**
+* @internal
+*/
+declare function parseIntegerOrDecimal(src: string): ParsedValue<number>;
+//#endregion
+//#region src/parse/parseItem.d.ts
+/**
+* @internal
+*/
+declare function parseItem(src: string, options?: SfDecodeOptions): ParsedValue<SfItem>;
+//#endregion
+//#region src/parse/parseItemOrInnerList.d.ts
+/**
+* @internal
+*/
+declare function parseItemOrInnerList(src: string, options?: SfDecodeOptions): ParsedValue<SfItem | SfInnerList>;
+//#endregion
+//#region src/parse/parseKey.d.ts
+/**
+* @internal
+*/
+declare function parseKey(src: string): ParsedValue<string>;
+//#endregion
+//#region src/parse/parseList.d.ts
+/**
+* @internal
+*/
+declare function parseList(src: string, options?: SfDecodeOptions): ParsedValue<SfMember[]>;
+//#endregion
+//#region src/parse/parseParameters.d.ts
+/**
+* @internal
+*/
+declare function parseParameters(src: string, options?: SfDecodeOptions): ParsedValue<SfParameters | undefined>;
+//#endregion
+//#region src/parse/parseString.d.ts
+/**
+* @internal
+*/
+declare function parseString(src: string): ParsedValue<string>;
+//#endregion
+//#region src/parse/parseToken.d.ts
+/**
+* @internal
+*/
+declare function parseToken(src: string, options?: SfDecodeOptions): ParsedValue<symbol | SfToken>;
+//#endregion
+//#region src/serialize/serializeBareItem.d.ts
+/**
+* @internal
+*/
+declare function serializeBareItem(value: any): string;
+//#endregion
+//#region src/serialize/serializeBoolean.d.ts
+/**
+* @internal
+*/
+declare function serializeBoolean(value: boolean): string;
+//#endregion
+//#region src/serialize/serializeByteSequence.d.ts
+/**
+* @internal
+*/
+declare function serializeByteSequence(value: Uint8Array): string;
+//#endregion
+//#region src/serialize/serializeDate.d.ts
+/**
+* @internal
+*/
+declare function serializeDate(value: Date): string;
+//#endregion
+//#region src/serialize/serializeDecimal.d.ts
+/**
+* @internal
+*/
+declare function serializeDecimal(value: number): string;
+//#endregion
+//#region src/serialize/serializeDict.d.ts
+/**
+* @internal
+*/
+declare function serializeDict(dict: Record<string, any> | Map<string, any>, options?: SfEncodeOptions): string;
+//#endregion
+//#region src/serialize/serializeError.d.ts
+/**
+* @internal
+*/
+declare function serializeError(src: any, type: string, cause?: any): Error;
+//#endregion
+//#region src/serialize/serializeInnerList.d.ts
+/**
+* @internal
+*/
+declare function serializeInnerList(value: SfInnerList): string;
+//#endregion
+//#region src/serialize/serializeInteger.d.ts
+/**
+* @internal
+*/
+declare function serializeInteger(value: number): string;
+//#endregion
+//#region src/serialize/serializeItem.d.ts
+/**
+* @internal
+*/
+declare function serializeItem(value: SfItem | SfBareItem): string;
+//#endregion
+//#region src/serialize/serializeKey.d.ts
+/**
+* @internal
+*/
+declare function serializeKey(value: string): string;
+//#endregion
+//#region src/serialize/serializeList.d.ts
+/**
+* @internal
+*/
+declare function serializeList(list: SfMember[], options?: SfEncodeOptions): string;
+//#endregion
+//#region src/serialize/serializeParams.d.ts
+/**
+* @internal
+*/
+declare function serializeParams(params?: Record<string, any>): string;
+//#endregion
+//#region src/serialize/serializeString.d.ts
+/**
+* @internal
+*/
+declare function serializeString(value: string): string;
+//#endregion
+//#region src/serialize/serializeToken.d.ts
+/**
+* @internal
+*/
+declare function serializeToken(token: symbol | SfToken): string;
+//#endregion
+export { ParsedValue, SfBareItem, SfDecodeOptions, SfDictionary, SfEncodeOptions, SfInnerList, SfItem, SfMember, SfParameters, SfToken, decodeSfDict, decodeSfItem, decodeSfList, encodeSfDict, encodeSfItem, encodeSfList, parseBareItem, parseBoolean, parseByteSequence, parseDate, parseDict, parseError, parseInnerList, parseIntegerOrDecimal, parseItem, parseItemOrInnerList, parseKey, parseList, parseParameters, parseString, parseToken, serializeBareItem, serializeBoolean, serializeByteSequence, serializeDate, serializeDecimal, serializeDict, serializeError, serializeInnerList, serializeInteger, serializeItem, serializeKey, serializeList, serializeParams, serializeString, serializeToken, symbolToStr };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,mBAAmB,iBAAiB,CAAC;AACrC,mBAAmB,sBAAsB,CAAC;AAC1C,mBAAmB,mBAAmB,CAAC;AACvC,mBAAmB,sBAAsB,CAAC;AAC1C,mBAAmB,kBAAkB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,mBAAmB,eAAe,CAAC;AACnC,mBAAmB,mBAAmB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/SfDecodeOptions.ts","../src/SfToken.ts","../src/SfBareItem.ts","../src/SfParameters.ts","../src/SfItem.ts","../src/SfInnerList.ts","../src/SfMember.ts","../src/SfDictionary.ts","../src/decodeSfDict.ts","../src/decodeSfItem.ts","../src/decodeSfList.ts","../src/SfEncodeOptions.ts","../src/encodeSfDict.ts","../src/encodeSfItem.ts","../src/encodeSfList.ts","../src/utils/symbolToStr.ts","../src/parse/ParsedValue.ts","../src/parse/parseBareItem.ts","../src/parse/parseBoolean.ts","../src/parse/parseByteSequence.ts","../src/parse/parseDate.ts","../src/parse/parseDict.ts","../src/parse/parseError.ts","../src/parse/parseInnerList.ts","../src/parse/parseIntegerOrDecimal.ts","../src/parse/parseItem.ts","../src/parse/parseItemOrInnerList.ts","../src/parse/parseKey.ts","../src/parse/parseList.ts","../src/parse/parseParameters.ts","../src/parse/parseString.ts","../src/parse/parseToken.ts","../src/serialize/serializeBareItem.ts","../src/serialize/serializeBoolean.ts","../src/serialize/serializeByteSequence.ts","../src/serialize/serializeDate.ts","../src/serialize/serializeDecimal.ts","../src/serialize/serializeDict.ts","../src/serialize/serializeError.ts","../src/serialize/serializeInnerList.ts","../src/serialize/serializeInteger.ts","../src/serialize/serializeItem.ts","../src/serialize/serializeKey.ts","../src/serialize/serializeList.ts","../src/serialize/serializeParams.ts","../src/serialize/serializeString.ts","../src/serialize/serializeToken.ts"],"sourcesContent":[],"mappings":"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"}