@pamoja/codec 0.1.15 → 0.1.16

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Ergonomic facade over the generated codec binding.
+ *
+ * JavaScript already has JSON, so the facade takes and returns ordinary values
+ * and does the encoding itself, leaving callers to think in documents rather than
+ * buffers. The conversion and the packing happen in the native core reached
+ * through the generated contract.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Encodes a value as CBOR, which is typically much smaller than its JSON form.
+ *
+ * @param value - Any JSON-serializable value, or the raw bytes of a JSON
+ * document.
+ * @returns The CBOR encoding.
+ * @throws If the value cannot be encoded.
+ */
+export declare function toCbor(value: unknown): Buffer;
+/**
+ * Decodes a CBOR document back into an ordinary JavaScript value.
+ *
+ * @param cbor - The CBOR document to decode.
+ * @returns The decoded value.
+ * @throws If the document is malformed, or holds a construct with no JSON
+ * equivalent such as a non-string map key.
+ */
+export declare function fromCbor(cbor: Uint8Array): unknown;
+/**
+ * Delta-encodes a series of integer samples into a compact buffer.
+ *
+ * @param samples - The samples, in order.
+ * @returns The packed encoding, far smaller than the samples for a slow-moving
+ * series.
+ */
+export declare function packSamples(samples: readonly number[]): Buffer;
+/**
+ * Unpacks a buffer produced by {@link packSamples}.
+ *
+ * @param bytes - The packed encoding.
+ * @returns The samples, in order.
+ * @throws If the buffer is malformed.
+ */
+export declare function unpackSamples(bytes: Uint8Array): number[];
+/**
+ * Packs float readings to a fixed precision, for a link that charges per byte.
+ *
+ * @example
+ * ```ts
+ * const quantizer = new Quantizer(100) // keep two decimal places
+ * const packed = quantizer.encode([20.0, 20.1, 20.2])
+ * quantizer.decode(packed) // [20.0, 20.1, 20.2], to within 0.01
+ * ```
+ */
+export declare class Quantizer {
+    #private;
+    /**
+     * Creates a quantizer at the given precision.
+     *
+     * @param scale - The multiplier applied before rounding; `100` keeps two
+     * decimal places. Must be positive and finite.
+     * @throws If the scale is not positive and finite.
+     */
+    constructor(scale: number);
+    /**
+     * Quantizes and packs a batch of readings.
+     *
+     * @param readings - The readings, in order.
+     * @returns The packed encoding.
+     */
+    encode(readings: readonly number[]): Buffer;
+    /**
+     * Unpacks a batch, to within this quantizer's precision.
+     *
+     * @param bytes - The encoding produced by {@link encode} at the same scale.
+     * @returns The readings, in order.
+     * @throws If the buffer is malformed.
+     */
+    decode(bytes: Uint8Array): number[];
+}

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Ergonomic facade over the generated codec binding.
+ *
+ * JavaScript already has JSON, so the facade takes and returns ordinary values
+ * and does the encoding itself, leaving callers to think in documents rather than
+ * buffers. The conversion and the packing happen in the native core reached
+ * through the generated contract.
+ *
+ * @packageDocumentation
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Quantizer_native;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Quantizer = void 0;
+exports.toCbor = toCbor;
+exports.fromCbor = fromCbor;
+exports.packSamples = packSamples;
+exports.unpackSamples = unpackSamples;
+const native_1 = require("@pamoja/native");
+/**
+ * Encodes a value as CBOR, which is typically much smaller than its JSON form.
+ *
+ * @param value - Any JSON-serializable value, or the raw bytes of a JSON
+ * document.
+ * @returns The CBOR encoding.
+ * @throws If the value cannot be encoded.
+ */
+function toCbor(value) {
+    const json = value instanceof Uint8Array ? Buffer.from(value) : Buffer.from(JSON.stringify(value), 'utf8');
+    return (0, native_1.jsonToCborBytes)(json);
+}
+/**
+ * Decodes a CBOR document back into an ordinary JavaScript value.
+ *
+ * @param cbor - The CBOR document to decode.
+ * @returns The decoded value.
+ * @throws If the document is malformed, or holds a construct with no JSON
+ * equivalent such as a non-string map key.
+ */
+function fromCbor(cbor) {
+    return JSON.parse((0, native_1.cborToJsonBytes)(Buffer.from(cbor)).toString('utf8'));
+}
+/**
+ * Delta-encodes a series of integer samples into a compact buffer.
+ *
+ * @param samples - The samples, in order.
+ * @returns The packed encoding, far smaller than the samples for a slow-moving
+ * series.
+ */
+function packSamples(samples) {
+    return (0, native_1.encodeDeltaSamples)(samples);
+}
+/**
+ * Unpacks a buffer produced by {@link packSamples}.
+ *
+ * @param bytes - The packed encoding.
+ * @returns The samples, in order.
+ * @throws If the buffer is malformed.
+ */
+function unpackSamples(bytes) {
+    return (0, native_1.decodeDeltaSamples)(Buffer.from(bytes));
+}
+/**
+ * Packs float readings to a fixed precision, for a link that charges per byte.
+ *
+ * @example
+ * ```ts
+ * const quantizer = new Quantizer(100) // keep two decimal places
+ * const packed = quantizer.encode([20.0, 20.1, 20.2])
+ * quantizer.decode(packed) // [20.0, 20.1, 20.2], to within 0.01
+ * ```
+ */
+class Quantizer {
+    /**
+     * Creates a quantizer at the given precision.
+     *
+     * @param scale - The multiplier applied before rounding; `100` keeps two
+     * decimal places. Must be positive and finite.
+     * @throws If the scale is not positive and finite.
+     */
+    constructor(scale) {
+        _Quantizer_native.set(this, void 0);
+        __classPrivateFieldSet(this, _Quantizer_native, new native_1.Quantizer(scale), "f");
+    }
+    /**
+     * Quantizes and packs a batch of readings.
+     *
+     * @param readings - The readings, in order.
+     * @returns The packed encoding.
+     */
+    encode(readings) {
+        return __classPrivateFieldGet(this, _Quantizer_native, "f").encode(readings);
+    }
+    /**
+     * Unpacks a batch, to within this quantizer's precision.
+     *
+     * @param bytes - The encoding produced by {@link encode} at the same scale.
+     * @returns The readings, in order.
+     * @throws If the buffer is malformed.
+     */
+    decode(bytes) {
+        return __classPrivateFieldGet(this, _Quantizer_native, "f").decode(Buffer.from(bytes));
+    }
+}
+exports.Quantizer = Quantizer;
+_Quantizer_native = new WeakMap();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pamoja/codec",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "CBOR, JSON, and raw codecs behind one trait, delta and varint batch packing, and an f32 quantizer for metered links.",
   "license": "MIT",
   "publishConfig": {
@@ -34,6 +34,6 @@
     "node": ">= 16"
   },
   "dependencies": {
-    "@pamoja/native": "0.1.15"
+    "@pamoja/native": "0.1.16"
   }
 }