@ac-kit/format-hid 0.0.0-stage → 0.1.1

package/dist/item/hid-item-value.js

@@ -0,0 +1,36 @@
+/**
+ * The item's data read as a little-endian unsigned integer — how HID 1.11
+ * §6.2.2.7 reads Usage Page, Report Size, Report Count, Report ID and Unit.
+ *
+ * Use {@link hidItemSigned} for Logical/Physical Minimum and other signed
+ * values. An empty data field reads as 0.
+ *
+ * @throws {RangeError} When the data is longer than 4 bytes (a long item).
+ */
+export function hidItemUnsigned(item) {
+    const { data } = item;
+    if (data.length > 4) {
+        throw new RangeError(`hidItemUnsigned: ${data.length} data bytes exceed the 4 an integer item holds`);
+    }
+    let value = 0;
+    for (let index = data.length - 1; index >= 0; index--) {
+        value = value * 256 + data[index];
+    }
+    return value;
+}
+/**
+ * The item's data read as a little-endian two's-complement integer of its own
+ * width — 1, 2 or 4 bytes — as HID 1.11 §6.2.2.7 reads Logical and Physical
+ * Minimum. An empty data field reads as 0.
+ *
+ * @throws {RangeError} When the data is longer than 4 bytes (a long item).
+ */
+export function hidItemSigned(item) {
+    const value = hidItemUnsigned(item);
+    const bits = item.data.length * 8;
+    if (bits === 0 || value < 2 ** (bits - 1)) {
+        return value;
+    }
+    return value - 2 ** bits;
+}
+//# sourceMappingURL=hid-item-value.js.map

package/dist/item/hid-item-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-item-value.js","sourceRoot":"","sources":["../../src/item/hid-item-value.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACtB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,UAAU,CACnB,oBAAoB,IAAI,CAAC,MAAM,gDAAgD,CAC/E,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACvD,KAAK,GAAG,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAE,CAAC;IACpC,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IAC1C,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACd,CAAC;IAED,OAAO,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC;AAC1B,CAAC"}

package/dist/item/hid-item.d.ts

@@ -0,0 +1,32 @@
+/** The `bType` field of a short item's prefix byte (HID 1.11 §6.2.2.2). */
+export type HidItemType = "main" | "global" | "local" | "reserved";
+/**
+ * A short item: a one-byte prefix carrying the type, the tag and a data length
+ * of 0, 1, 2 or 4 bytes (HID 1.11 §6.2.2.2).
+ */
+export type HidShortItem = {
+    kind: "short";
+    type: HidItemType;
+    /**
+     * `bTag`, 0–15. Its meaning depends on `type`: see {@link HidMainTag},
+     * {@link HidGlobalTag} and {@link HidLocalTag}.
+     */
+    tag: number;
+    /** Raw little-endian data, 0, 1, 2 or 4 bytes long. */
+    data: Uint8Array;
+};
+/**
+ * A long item: prefix `0xFE`, a one-byte data length and a one-byte tag (HID
+ * 1.11 §6.2.2.3). HID 1.11 defines no long item tag, so these only ever carry
+ * vendor data.
+ */
+export type HidLongItem = {
+    kind: "long";
+    /** `bLongItemTag`, 0–255. */
+    tag: number;
+    /** Raw data, 0–255 bytes long. */
+    data: Uint8Array;
+};
+/** One item of a report descriptor, as it appears on the wire. */
+export type HidItem = HidShortItem | HidLongItem;
+//# sourceMappingURL=hid-item.d.ts.map

package/dist/item/hid-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-item.d.ts","sourceRoot":"","sources":["../../src/item/hid-item.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,IAAI,EAAE,UAAU,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,UAAU,CAAC;CACjB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC"}

package/dist/item/hid-item.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hid-item.js.map

package/dist/item/hid-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-item.js","sourceRoot":"","sources":["../../src/item/hid-item.ts"],"names":[],"mappings":""}

package/dist/unit/decode-hid-unit.d.ts

@@ -0,0 +1,9 @@
+import type { HidUnit } from "./hid-unit.js";
+/**
+ * Splits a unit word — a field's {@link HidReportField.unit} — into its system
+ * and the exponent of each base quantity (HID 1.11 §6.2.2.7).
+ *
+ * @throws {RangeError} When `word` is not an integer in 0–0xFFFFFFFF.
+ */
+export declare function decodeHidUnit(word: number): HidUnit;
+//# sourceMappingURL=decode-hid-unit.d.ts.map

package/dist/unit/decode-hid-unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-hid-unit.d.ts","sourceRoot":"","sources":["../../src/unit/decode-hid-unit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAQ7C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBnD"}

package/dist/unit/decode-hid-unit.js

@@ -0,0 +1,26 @@
+function signedNibble_(word, nibble) {
+    const value = (word >>> (nibble * 4)) & 0xf;
+    return value >= 8 ? value - 16 : value;
+}
+/**
+ * Splits a unit word — a field's {@link HidReportField.unit} — into its system
+ * and the exponent of each base quantity (HID 1.11 §6.2.2.7).
+ *
+ * @throws {RangeError} When `word` is not an integer in 0–0xFFFFFFFF.
+ */
+export function decodeHidUnit(word) {
+    if (!Number.isInteger(word) || word < 0 || word > 4294967295) {
+        throw new RangeError(`decodeHidUnit: ${word} is not a 32-bit unsigned integer`);
+    }
+    return {
+        system: word & 0xf,
+        length: signedNibble_(word, 1),
+        mass: signedNibble_(word, 2),
+        time: signedNibble_(word, 3),
+        temperature: signedNibble_(word, 4),
+        current: signedNibble_(word, 5),
+        luminousIntensity: signedNibble_(word, 6),
+        reserved: word >>> 28,
+    };
+}
+//# sourceMappingURL=decode-hid-unit.js.map

package/dist/unit/decode-hid-unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-hid-unit.js","sourceRoot":"","sources":["../../src/unit/decode-hid-unit.ts"],"names":[],"mappings":"AAEA,SAAS,aAAa,CAAC,IAAY,EAAE,MAAc;IAClD,MAAM,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAE5C,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,UAAW,EAAE,CAAC;QAC/D,MAAM,IAAI,UAAU,CACnB,kBAAkB,IAAI,mCAAmC,CACzD,CAAC;IACH,CAAC;IAED,OAAO;QACN,MAAM,EAAE,IAAI,GAAG,GAAG;QAClB,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9B,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5B,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5B,WAAW,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QACnC,OAAO,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/B,iBAAiB,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,QAAQ,EAAE,IAAI,KAAK,EAAE;KACrB,CAAC;AACH,CAAC"}

package/dist/unit/encode-hid-unit.d.ts

@@ -0,0 +1,10 @@
+import type { HidUnit } from "./hid-unit.js";
+/**
+ * Packs a unit into the 32-bit word a Unit item carries — the inverse of
+ * {@link decodeHidUnit}.
+ *
+ * @throws {RangeError} When `system` or `reserved` is not 0–15, or an exponent
+ *   is not an integer in -8–7.
+ */
+export declare function encodeHidUnit(unit: HidUnit): number;
+//# sourceMappingURL=encode-hid-unit.d.ts.map

package/dist/unit/encode-hid-unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode-hid-unit.d.ts","sourceRoot":"","sources":["../../src/unit/encode-hid-unit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAwB7C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAYnD"}

package/dist/unit/encode-hid-unit.js

@@ -0,0 +1,32 @@
+const EXPONENTS_ = [
+    "length",
+    "mass",
+    "time",
+    "temperature",
+    "current",
+    "luminousIntensity",
+];
+function checkNibble_(name, value, minimum, maximum) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new RangeError(`encodeHidUnit: ${name} ${value} is not ${minimum}–${maximum}`);
+    }
+}
+/**
+ * Packs a unit into the 32-bit word a Unit item carries — the inverse of
+ * {@link decodeHidUnit}.
+ *
+ * @throws {RangeError} When `system` or `reserved` is not 0–15, or an exponent
+ *   is not an integer in -8–7.
+ */
+export function encodeHidUnit(unit) {
+    checkNibble_("system", unit.system, 0, 15);
+    checkNibble_("reserved", unit.reserved, 0, 15);
+    let word = unit.system;
+    for (const [index, name] of EXPONENTS_.entries()) {
+        const exponent = unit[name];
+        checkNibble_(name, exponent, -8, 7);
+        word |= (exponent & 0xf) << ((index + 1) * 4);
+    }
+    return (word | (unit.reserved << 28)) >>> 0;
+}
+//# sourceMappingURL=encode-hid-unit.js.map

package/dist/unit/encode-hid-unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode-hid-unit.js","sourceRoot":"","sources":["../../src/unit/encode-hid-unit.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAG;IAClB,QAAQ;IACR,MAAM;IACN,MAAM;IACN,aAAa;IACb,SAAS;IACT,mBAAmB;CAC2B,CAAC;AAEhD,SAAS,YAAY,CACpB,IAAY,EACZ,KAAa,EACb,OAAe,EACf,OAAe;IAEf,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,OAAO,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;QACpE,MAAM,IAAI,UAAU,CACnB,kBAAkB,IAAI,IAAI,KAAK,WAAW,OAAO,IAAI,OAAO,EAAE,CAC9D,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IAC1C,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3C,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAE/C,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;IACvB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC"}

package/dist/unit/hid-unit.d.ts

@@ -0,0 +1,29 @@
+/** Nibble 0 of a unit word (HID 1.11 §6.2.2.7). 5–14 are reserved. */
+export declare enum HidUnitSystem {
+    NONE = 0,
+    SI_LINEAR = 1,
+    SI_ROTATION = 2,
+    ENGLISH_LINEAR = 3,
+    ENGLISH_ROTATION = 4,
+    VENDOR_DEFINED = 15
+}
+/**
+ * A unit word split into its nibbles. Each dimension is the signed exponent of
+ * that base quantity, -8–7: `{ system: SI_LINEAR, length: 1, time: -2 }` is
+ * cm·s⁻². What "length" means — centimetre, inch, radian, degree — depends on
+ * `system`.
+ */
+export type HidUnit = {
+    /** A {@link HidUnitSystem}, or the raw nibble of a reserved one. */
+    system: number;
+    /** Length, or angle in a rotation system. */
+    length: number;
+    mass: number;
+    time: number;
+    temperature: number;
+    current: number;
+    luminousIntensity: number;
+    /** Nibble 7, reserved; 0–15, kept so a word round-trips. */
+    reserved: number;
+};
+//# sourceMappingURL=hid-unit.d.ts.map

package/dist/unit/hid-unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-unit.d.ts","sourceRoot":"","sources":["../../src/unit/hid-unit.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,oBAAY,aAAa;IACxB,IAAI,IAAM;IACV,SAAS,IAAM;IACf,WAAW,IAAM;IACjB,cAAc,IAAM;IACpB,gBAAgB,IAAM;IACtB,cAAc,KAAM;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG;IACrB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/unit/hid-unit.js

@@ -0,0 +1,11 @@
+/** Nibble 0 of a unit word (HID 1.11 §6.2.2.7). 5–14 are reserved. */
+export var HidUnitSystem;
+(function (HidUnitSystem) {
+    HidUnitSystem[HidUnitSystem["NONE"] = 0] = "NONE";
+    HidUnitSystem[HidUnitSystem["SI_LINEAR"] = 1] = "SI_LINEAR";
+    HidUnitSystem[HidUnitSystem["SI_ROTATION"] = 2] = "SI_ROTATION";
+    HidUnitSystem[HidUnitSystem["ENGLISH_LINEAR"] = 3] = "ENGLISH_LINEAR";
+    HidUnitSystem[HidUnitSystem["ENGLISH_ROTATION"] = 4] = "ENGLISH_ROTATION";
+    HidUnitSystem[HidUnitSystem["VENDOR_DEFINED"] = 15] = "VENDOR_DEFINED";
+})(HidUnitSystem || (HidUnitSystem = {}));
+//# sourceMappingURL=hid-unit.js.map

package/dist/unit/hid-unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hid-unit.js","sourceRoot":"","sources":["../../src/unit/hid-unit.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,CAAN,IAAY,aAOX;AAPD,WAAY,aAAa;IACxB,iDAAU,CAAA;IACV,2DAAe,CAAA;IACf,+DAAiB,CAAA;IACjB,qEAAoB,CAAA;IACpB,yEAAsB,CAAA;IACtB,sEAAoB,CAAA;AACrB,CAAC,EAPW,aAAa,KAAb,aAAa,QAOxB"}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@ac-kit/format-hid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "USB HID 1.11 report descriptors: item codec, semantic parse into reports and fields, bit-level field access and the unit word.",
+  "keywords": [
+    "hid",
+    "hidraw",
+    "report-descriptor",
+    "usb",
+    "usb-hid"
+  ],
+  "homepage": "https://anthochamp.github.io/node-essentials/api/format-hid/",
+  "bugs": {
+    "url": "https://git.grenadine.io/anthochamp/node-essentials/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anthony Champagne <dev@anthonychampagne.fr>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.grenadine.io/anthochamp/node-essentials.git",
+    "directory": "packages/format-hid"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "exports": {
+      ".": "./dist/index.js"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc -p ./tsconfig.build.json -outDir dist",
+    "compile:check": "tsc -noEmit -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn compile",
+    "test": "yarn run -T vitest run",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ac-kit/core": "^0.4.0",
+    "@types/web": "^0.0.359"
+  },
+  "devDependencies": {
+    "@ac-kit/tsconfig": "0.1.0",
+    "@ac-kit/typedoc-config": "0.1.0",
+    "@ac-kit/vitest-config": "0.1.1",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  }
 }