@bcts/dcbor 1.0.0-alpha.10

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@bcts/dcbor",
+  "version": "1.0.0-alpha.10",
+  "type": "module",
+  "description": "Blockchain Commons Deterministic CBOR (dCBOR) for TypeScript",
+  "license": "BSD-2-Clause-Patent",
+  "author": "Leonardo Custodio <leonardo@custodio.me>",
+  "homepage": "https://bcts.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leonardocustodio/bcts",
+    "directory": "packages/dcbor"
+  },
+  "bugs": {
+    "url": "https://github.com/leonardocustodio/bcts/issues"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "browser": "dist/index.iife.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cli": "vitest run tests/cli.test.ts",
+    "test:examples": "npm run build && node scripts/test-examples.js",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "cbor",
+    "dcbor",
+    "deterministic",
+    "blockchain-commons",
+    "encoding",
+    "serialization",
+    "codec",
+    "binary"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@bcts/eslint": "^0.1.0",
+    "@bcts/tsconfig": "^0.1.0",
+    "@eslint/js": "^9.39.2",
+    "@types/collections": "^5.1.5",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "ts-node": "^10.9.2",
+    "tsdown": "^0.18.3",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "byte-data": "^19.0.1",
+    "collections": "^5.1.13"
+  }
+}

package/src/.claude-flow/metrics/agent-metrics.json

@@ -0,0 +1 @@
+{}

package/src/.claude-flow/metrics/performance.json

@@ -0,0 +1,87 @@
+{
+  "startTime": 1764550116519,
+  "sessionId": "session-1764550116519",
+  "lastActivity": 1764550116519,
+  "sessionDuration": 0,
+  "totalTasks": 1,
+  "successfulTasks": 1,
+  "failedTasks": 0,
+  "totalAgents": 0,
+  "activeAgents": 0,
+  "neuralEvents": 0,
+  "memoryMode": {
+    "reasoningbankOperations": 0,
+    "basicOperations": 0,
+    "autoModeSelections": 0,
+    "modeOverrides": 0,
+    "currentMode": "auto"
+  },
+  "operations": {
+    "store": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    },
+    "retrieve": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    },
+    "query": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    },
+    "list": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    },
+    "delete": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    },
+    "search": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    },
+    "init": {
+      "count": 0,
+      "totalDuration": 0,
+      "errors": 0
+    }
+  },
+  "performance": {
+    "avgOperationDuration": 0,
+    "minOperationDuration": null,
+    "maxOperationDuration": null,
+    "slowOperations": 0,
+    "fastOperations": 0,
+    "totalOperationTime": 0
+  },
+  "storage": {
+    "totalEntries": 0,
+    "reasoningbankEntries": 0,
+    "basicEntries": 0,
+    "databaseSize": 0,
+    "lastBackup": null,
+    "growthRate": 0
+  },
+  "errors": {
+    "total": 0,
+    "byType": {},
+    "byOperation": {},
+    "recent": []
+  },
+  "reasoningbank": {
+    "semanticSearches": 0,
+    "sqlFallbacks": 0,
+    "embeddingGenerated": 0,
+    "consolidations": 0,
+    "avgQueryTime": 0,
+    "cacheHits": 0,
+    "cacheMisses": 0
+  }
+}

package/src/.claude-flow/metrics/task-metrics.json

@@ -0,0 +1,10 @@
+[
+  {
+    "id": "cmd-hooks-1764550116550",
+    "type": "hooks",
+    "success": true,
+    "duration": 3.348541999999995,
+    "timestamp": 1764550116553,
+    "metadata": {}
+  }
+]

package/src/byte-string.ts

@@ -0,0 +1,300 @@
+/**
+ * Byte string utilities for dCBOR.
+ *
+ * Represents a CBOR byte string (major type 2).
+ *
+ * `ByteString` is a wrapper around a byte array, optimized for use in CBOR
+ * encoding and decoding operations. It provides a richer API for working with
+ * byte data in the context of CBOR compared to using raw `Uint8Array` values.
+ *
+ * In dCBOR, byte strings follow the general deterministic encoding rules:
+ * - They must use definite-length encoding
+ * - Their length must be encoded in the shortest possible form
+ *
+ * @module byte-string
+ */
+
+import { type Cbor, MajorType, cbor as toCbor } from "./cbor";
+import { CborError } from "./error";
+
+/**
+ * Represents a CBOR byte string (major type 2).
+ *
+ * Use Cases:
+ * - Binary data such as images, audio, or other non-text content
+ * - Cryptographic values like hashes, signatures, and public keys
+ * - Embedded CBOR (wrapped with tag 24)
+ * - Other serialized data formats embedded in CBOR
+ *
+ * @example
+ * ```typescript
+ * // Creating a byte string from various sources
+ * const bytes1 = new ByteString(new Uint8Array([1, 2, 3, 4]));
+ * const bytes2 = ByteString.from([5, 6, 7, 8]);
+ * const bytes3 = ByteString.from(new Uint8Array([9, 10, 11, 12]));
+ *
+ * // Converting to and from CBOR
+ * const cborValue = bytes1.toCbor();
+ *
+ * // ByteString provides Uint8Array-like operations
+ * const bytes = new ByteString(new Uint8Array([1, 2]));
+ * bytes.extend(new Uint8Array([3, 4]));
+ * assert(bytes.len() === 4);
+ * assert.deepEqual(bytes.data(), new Uint8Array([1, 2, 3, 4]));
+ * ```
+ */
+export class ByteString {
+  #data: Uint8Array;
+
+  /**
+   * Creates a new `ByteString` from a Uint8Array or array of bytes.
+   *
+   * @param data - The byte data
+   *
+   * @example
+   * ```typescript
+   * // From a Uint8Array
+   * const bytes1 = new ByteString(new Uint8Array([1, 2, 3, 4]));
+   *
+   * // From a number array
+   * const bytes2 = new ByteString(new Uint8Array([5, 6, 7, 8]));
+   * ```
+   */
+  constructor(data: Uint8Array | number[]) {
+    if (Array.isArray(data)) {
+      this.#data = new Uint8Array(data);
+    } else {
+      this.#data = new Uint8Array(data);
+    }
+  }
+
+  /**
+   * Creates a new `ByteString` from various input types.
+   *
+   * @param data - Uint8Array, number array, or string
+   * @returns New ByteString instance
+   *
+   * @example
+   * ```typescript
+   * const bytes1 = ByteString.from([1, 2, 3, 4]);
+   * const bytes2 = ByteString.from(new Uint8Array([5, 6, 7, 8]));
+   * const bytes3 = ByteString.from("hello");
+   * ```
+   */
+  static from(data: Uint8Array | number[] | string): ByteString {
+    if (typeof data === "string") {
+      return new ByteString(new TextEncoder().encode(data));
+    }
+    return new ByteString(data);
+  }
+
+  /**
+   * Returns a reference to the underlying byte data.
+   *
+   * @returns The raw bytes
+   *
+   * @example
+   * ```typescript
+   * const bytes = new ByteString(new Uint8Array([1, 2, 3, 4]));
+   * assert.deepEqual(bytes.data(), new Uint8Array([1, 2, 3, 4]));
+   *
+   * // You can use standard slice operations on the result
+   * assert.deepEqual(bytes.data().slice(1, 3), new Uint8Array([2, 3]));
+   * ```
+   */
+  data(): Uint8Array {
+    return this.#data;
+  }
+
+  /**
+   * Returns the length of the byte string in bytes.
+   *
+   * @returns Number of bytes
+   *
+   * @example
+   * ```typescript
+   * const empty = new ByteString(new Uint8Array([]));
+   * assert(empty.len() === 0);
+   *
+   * const bytes = new ByteString(new Uint8Array([1, 2, 3, 4]));
+   * assert(bytes.len() === 4);
+   * ```
+   */
+  len(): number {
+    return this.#data.length;
+  }
+
+  /**
+   * Returns `true` if the byte string contains no bytes.
+   *
+   * @returns true if empty
+   *
+   * @example
+   * ```typescript
+   * const empty = new ByteString(new Uint8Array([]));
+   * assert(empty.isEmpty());
+   *
+   * const bytes = new ByteString(new Uint8Array([1, 2, 3, 4]));
+   * assert(!bytes.isEmpty());
+   * ```
+   */
+  isEmpty(): boolean {
+    return this.#data.length === 0;
+  }
+
+  /**
+   * Extends the byte string with additional bytes.
+   *
+   * @param other - Bytes to append
+   *
+   * @example
+   * ```typescript
+   * const bytes = new ByteString(new Uint8Array([1, 2]));
+   * bytes.extend(new Uint8Array([3, 4]));
+   * assert.deepEqual(bytes.data(), new Uint8Array([1, 2, 3, 4]));
+   *
+   * // You can extend with different types
+   * bytes.extend([5, 6]);
+   * assert.deepEqual(bytes.data(), new Uint8Array([1, 2, 3, 4, 5, 6]));
+   * ```
+   */
+  extend(other: Uint8Array | number[]): void {
+    const otherArray = Array.isArray(other) ? new Uint8Array(other) : other;
+    const newData = new Uint8Array(this.#data.length + otherArray.length);
+    newData.set(this.#data, 0);
+    newData.set(otherArray, this.#data.length);
+    this.#data = newData;
+  }
+
+  /**
+   * Creates a new Uint8Array containing a copy of the byte string's data.
+   *
+   * @returns Copy of the data
+   *
+   * @example
+   * ```typescript
+   * const bytes = new ByteString(new Uint8Array([1, 2, 3, 4]));
+   * const arr = bytes.toUint8Array();
+   * assert.deepEqual(arr, new Uint8Array([1, 2, 3, 4]));
+   *
+   * // The returned array is a clone, so you can modify it independently
+   * const arr2 = bytes.toUint8Array();
+   * arr2[0] = 99;
+   * assert.deepEqual(bytes.data(), new Uint8Array([1, 2, 3, 4])); // original unchanged
+   * ```
+   */
+  toUint8Array(): Uint8Array {
+    return new Uint8Array(this.#data);
+  }
+
+  /**
+   * Returns an iterator over the bytes in the byte string.
+   *
+   * @returns Iterator yielding each byte
+   *
+   * @example
+   * ```typescript
+   * const bytes = new ByteString(new Uint8Array([1, 2, 3]));
+   * const iter = bytes.iter();
+   *
+   * assert(iter.next().value === 1);
+   * assert(iter.next().value === 2);
+   * assert(iter.next().value === 3);
+   * assert(iter.next().done);
+   *
+   * // You can also use for loops
+   * let sum = 0;
+   * for (const byte of bytes) {
+   *   sum += byte;
+   * }
+   * assert(sum === 6);
+   * ```
+   */
+  iter(): Iterator<number> {
+    return this.#data.values();
+  }
+
+  /**
+   * Makes ByteString iterable.
+   */
+  [Symbol.iterator](): Iterator<number> {
+    return this.iter();
+  }
+
+  /**
+   * Converts the ByteString to a CBOR value.
+   *
+   * @returns CBOR byte string
+   *
+   * @example
+   * ```typescript
+   * const bytes = new ByteString(new Uint8Array([1, 2, 3, 4]));
+   * const cborValue = bytes.toCbor();
+   * ```
+   */
+  toCbor(): Cbor {
+    return toCbor(this.#data);
+  }
+
+  /**
+   * Attempts to convert a CBOR value into a ByteString.
+   *
+   * @param cbor - CBOR value
+   * @returns ByteString if successful
+   * @throws Error if the CBOR value is not a byte string
+   *
+   * @example
+   * ```typescript
+   * const cborValue = toCbor(new Uint8Array([1, 2, 3, 4]));
+   * const bytes = ByteString.fromCbor(cborValue);
+   * assert.deepEqual(bytes.data(), new Uint8Array([1, 2, 3, 4]));
+   *
+   * // Converting from a different CBOR type throws
+   * const cborInt = toCbor(42);
+   * try {
+   *   ByteString.fromCbor(cborInt); // throws
+   * } catch(e) {
+   *   // Error: Wrong type
+   * }
+   * ```
+   */
+  static fromCbor(cbor: Cbor): ByteString {
+    if (cbor.type !== MajorType.ByteString) {
+      throw new CborError({ type: "WrongType" });
+    }
+    return new ByteString(cbor.value);
+  }
+
+  /**
+   * Get element at index.
+   *
+   * @param index - Index to access
+   * @returns Byte at index or undefined
+   */
+  at(index: number): number | undefined {
+    return this.#data[index];
+  }
+
+  /**
+   * Equality comparison.
+   *
+   * @param other - ByteString to compare with
+   * @returns true if equal
+   */
+  equals(other: ByteString): boolean {
+    if (this.#data.length !== other.#data.length) return false;
+    for (let i = 0; i < this.#data.length; i++) {
+      if (this.#data[i] !== other.#data[i]) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Clone this ByteString.
+   *
+   * @returns New ByteString with copied data
+   */
+  clone(): ByteString {
+    return new ByteString(this.toUint8Array());
+  }
+}

package/src/cbor-codable.ts

@@ -0,0 +1,170 @@
+/**
+ * CBOR Encoding and Decoding Interfaces.
+ *
+ * These interfaces provide functionality for converting between TypeScript types and
+ * CBOR data. They form the foundation of the dCBOR serialization
+ * infrastructure.
+ *
+ * The main interfaces are:
+ *
+ * - `CborEncodable`: For types that can be encoded to CBOR
+ * - `CborDecodable`: For types that can be decoded from CBOR
+ * - `CborCodable`: For types that can do both (a combination of the above)
+ *
+ * These interfaces allow for ergonomic conversions using TypeScript's type system and
+ * enable seamless integration with dCBOR's deterministic encoding rules.
+ *
+ * @module cbor-codable
+ */
+
+import type { Cbor } from "./cbor";
+
+/**
+ * Interface for types that can be encoded to CBOR.
+ *
+ * This interface provides convenient methods for converting
+ * instances into CBOR objects and binary data.
+ *
+ * @example
+ * ```typescript
+ * // Custom type that can convert to CBOR
+ * class Person implements CborEncodable {
+ *   constructor (public name: string, public age: number) {}
+ *
+ *   toCbor(): Cbor {
+ *     const map = new CborMap();
+ *     map.set(cbor('name'), cbor(this.name));
+ *     map.set(cbor('age'), cbor(this.age));
+ *     return cbor(map);
+ *   }
+ *
+ *   toCborData(): Uint8Array {
+ *     return cborData(this.toCbor());
+ *   }
+ * }
+ *
+ * // Use the interface
+ * const person = new Person('Alice', 30);
+ *
+ * // Convert to CBOR
+ * const cborValue = person.toCbor();
+ *
+ * // Convert directly to binary CBOR data
+ * const data = person.toCborData();
+ * ```
+ */
+export interface CborEncodable {
+  /**
+   * Converts this value to a CBOR object.
+   *
+   * @returns CBOR representation
+   */
+  toCbor(): Cbor;
+
+  /**
+   * Converts this value directly to binary CBOR data.
+   *
+   * This is a shorthand for `cborData(this.toCbor())`.
+   *
+   * @returns Binary CBOR data
+   */
+  toCborData(): Uint8Array;
+}
+
+/**
+ * Interface for types that can be decoded from CBOR.
+ *
+ * This interface serves as a marker to indicate that a type
+ * supports being created from CBOR data.
+ *
+ * @typeParam T - The type being decoded
+ *
+ * @example
+ * ```typescript
+ * // Custom type that can be decoded from CBOR
+ * class Person implements CborDecodable<Person> {
+ *   constructor(public name: string = '', public age: number = 0) {}
+ *
+ *   static fromCbor(cbor: Cbor): Person {
+ *     if (cbor.type !== MajorType.Map) {
+ *       throw new Error('Expected a CBOR map');
+ *     }
+ *     const map = cbor.value as CborMap;
+ *     const name = extractCbor(map.get(cbor('name'))!) as string;
+ *     const age = extractCbor(map.get(cbor('age'))!) as number;
+ *     return new Person(name, age);
+ *   }
+ *
+ *   tryFromCbor(cbor: Cbor): Person {
+ *     return Person.fromCbor(cbor);
+ *   }
+ * }
+ *
+ * // Parse from CBOR
+ * const cborMap = ...; // some CBOR map
+ * const person = Person.fromCbor(cborMap);
+ * ```
+ */
+export interface CborDecodable<T> {
+  /**
+   * Try to create an instance from a CBOR value.
+   *
+   * @param cbor - CBOR value to decode
+   * @returns Decoded instance
+   * @throws Error if decoding fails
+   */
+  tryFromCbor(cbor: Cbor): T;
+}
+
+/**
+ * Interface for types that can be both encoded to and decoded from CBOR.
+ *
+ * This interface is a convenience marker for types that implement both
+ * `CborEncodable` and `CborDecodable`. It serves to indicate full CBOR
+ * serialization support.
+ *
+ * @typeParam T - The type being encoded/decoded
+ *
+ * @example
+ * ```typescript
+ * // Custom type that implements both conversion directions
+ * class Person implements CborCodable<Person> {
+ *   constructor(public name: string = '', public age: number = 0) {}
+ *
+ *   // Implement encoding to CBOR
+ *   toCbor(): Cbor {
+ *     const map = new CborMap();
+ *     map.set(cbor('name'), cbor(this.name));
+ *     map.set(cbor('age'), cbor(this.age));
+ *     return cbor(map);
+ *   }
+ *
+ *   toCborData(): Uint8Array {
+ *     return cborData(this.toCbor());
+ *   }
+ *
+ *   // Implement decoding from CBOR
+ *   static fromCbor(cbor: Cbor): Person {
+ *     if (cbor.type !== MajorType.Map) {
+ *       throw new Error('Expected a CBOR map');
+ *     }
+ *     const map = cbor.value as CborMap;
+ *     const name = extractCbor(map.get(cbor('name'))!) as string;
+ *     const age = extractCbor(map.get(cbor('age'))!) as number;
+ *     return new Person(name, age);
+ *   }
+ *
+ *   tryFromCbor(cbor: Cbor): Person {
+ *     return Person.fromCbor(cbor);
+ *   }
+ * }
+ *
+ * // Person now implements CborCodable
+ * const person = new Person('Alice', 30);
+ * const cborValue = person.toCbor(); // Using CborEncodable
+ *
+ * // Create a round-trip copy
+ * const personCopy = Person.fromCbor(cborValue); // Using CborDecodable
+ * ```
+ */
+export interface CborCodable<T> extends CborEncodable, CborDecodable<T> {}