@ac-kit/core 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# @ac-kit/core
+
+## 0.3.0
+
+### Minor Changes
+
+- a5c4d66: **Breaking:** `bigIntToBytesBe` and `bigIntFromBytesBe` move from
+  `@ac-kit/math-integer` to `@ac-kit/core`. Update the import specifier; the
+  behaviour is unchanged.
+  
+  They are a wire encoding rather than arithmetic — X.690 §8.3 for an ASN.1
+  INTEGER, and what `BigInteger.toByteArray` and `int.to_bytes` produce — and
+  their callers need no integer theory at all, while `math-integer` sits too high
+  in the dependency graph for some of them to reach it.
+  
+  New in `@ac-kit/core`: `bigIntToBytesLe` and `bigIntFromBytesLe`, the same
+  two's-complement, minimal-or-fixed-width encoding with the least significant
+  byte first.
+  
+  `@ac-kit/format-asn1` no longer depends on `@ac-kit/math-integer`.
+- a5c4d66: - **Breaking:** `InetAddress`, `InetEndpoint` and `composeInetAddress` are gone,
+    and so are `EPHEMERAL_PORT_MIN_VALUE`, `EPHEMERAL_PORT_MAX_VALUE` and
+    `getRandomEphemeralPort`. `core` holds language extensions and wrappers over
+    simple Web APIs, and `ARCHITECTURE.md` §3 names IP addressing as the example
+    of something pure that is nonetheless domain knowledge. The first three are
+    now `@ac-kit/node`'s, where `composeInetAddress` is spelled `toInetAddress`;
+    the ephemeral port range is `@ac-kit/net-address`'s, beside the rest of the
+    RFC 6335 port semantics. No compatibility re-export is left behind.
+  - New `flattenRecord(source, options)` and `unflattenRecord(source, options)`,
+    collapsing a nested record to delimiter-joined keys and back. A multi-segment
+    path can never reach `__proto__`, `constructor` or `prototype`; a
+    single-segment key is a leaf and is kept as one, because a record of
+    environment variables should still be able to hold one called `constructor`.
+    An array is a leaf value by default rather than being numbered, since an index
+    is the one segment a flattened key cannot tell apart from an ordinary key
+    spelled `"0"`. A key that itself contains the delimiter is not escaped and the
+    delimiter wins on the way back, so the round trip holds exactly for keys that
+    do not contain one.
+  - New `bytesMap(bytes, map)` and `bytesCombine(a, b, combine)`, applying a
+    function to every octet of one array or to every octet pair of two. Both mask
+    the callback's result to a single octet, so `~byte` and `left & right` read as
+    the bitwise operations they are rather than trailing an `& 0xff` that is easy
+    to forget and silent when it is. `bytesCombine` throws on mismatched lengths
+    instead of pairing up to the shorter array: a bitwise operation over two
+    different widths has no meaning, and truncating to the shorter one turns that
+    into a wrong answer rather than an error.
+  - New `nextUtf8Boundary(bytes, index)`, the first UTF-8 character boundary at or
+    after `index`. Slicing a UTF-8 buffer at an arbitrary offset — a tail, a
+    window, a chunk handed to `decodeText` — can land inside a multi-byte
+    sequence, whose orphaned tail decodes to a leading U+FFFD; aligning the offset
+    forward drops the partial character instead.
+  - Five more ASCII predicates: `isAsciiControl`, `isAsciiGraphic`,
+    `isAsciiPrintable`, `isAsciiPunctuation` and `isAsciiBlank` — C's `iscntrl`,
+    `isgraph`, `isprint`, `ispunct` and `isblank`, joining the `isalpha`/`isdigit`
+    family already here. Where `punct` stops and `graph` starts is exactly the kind
+    of boundary a hand-written range table gets subtly wrong, and every copy of it
+    gets it wrong differently.
+
+## 0.2.0
+
+### Minor Changes
+
+- a493b4a: Clarify the object type guards, which were three near-synonyms with one honest
+  doc comment between them.
+  
+  `isObject` and `isPojo` keep their names and behaviour and now say which
+  question each answers, and which sibling answers the other two. In short:
+  `isObject` asks whether there is a non-array object here at all; `isPojo` asks
+  whether it is a data bag, following the prototype chain; `hasObjectPrototype`
+  asks the same of the *own* prototype only, so `Object.create({})` fails it.
+  
+  **Breaking:** `isPlainObject` is now `hasObjectPrototype`. The old name was a
+  trap — everywhere else in the ecosystem `isPlainObject` means what this package
+  calls `isPojo`, so a caller reaching for the familiar name got the strictest
+  check in the family. It was never exported from the barrel, so this only affects
+  a deep import.
+- a493b4a: **Breaking:** the shell quoting and environment variable helpers have moved to
+  the new `@ac-kit/format-shell`.
+  
+  Moved as-is: `escapePosixShSqe`, `escapePosixShCommandArg`,
+  `escapePosixShCommand`, `escapeWin32CmdCommandArg`, `escapeWin32CmdCommand`.
+  
+  Moved and reshaped — see the `@ac-kit/format-shell` entry for why:
+  `stringifyEnvVariable` is `printEnvAssignment`, `stringifyEnvVariableValue` is
+  `printEnvValue`, `stringifyEnvVariableBoolValue` is `printEnvBoolValue`,
+  `parseEnvVariable` is `parseEnvAssignment`, and `parseEnvVariableValueAsBool`
+  and `parseEnvVariableValueAsNumber` drop `Variable` from their names.
+  `parseEnvVariableValue` and `parseEnvVariableValueAsString` are gone: parsing no
+  longer guesses a type, so `FOO=42` reads as `"42"` rather than `42`.
+- a493b4a: Harden every object helper that writes a key it did not choose, and export the
+  two primitives the rest of the tree now uses.
+  
+  - `setRecordEntry(record, key, value)` — assigns through `Object.defineProperty`
+    for `__proto__` and by plain assignment for everything else, so a record built
+    from parsed text can hold any key without reaching the prototype setter. The
+    record stays an ordinary object: same prototype, same spread, same
+    `deepEqual`.
+  - `isUnsafeRecordKey(key)` — true for `__proto__`, `constructor` and
+    `prototype`. A path walk needs this rather than `setRecordEntry`, because
+    stepping through `constructor` and then `prototype` pollutes on the *reads*,
+    before any assignment happens.
+  
+  **Breaking:**
+  
+  - `merge`, `mergeAll`, `mergeInplace`, `mergeAllInplace` and `defaults` now read
+    a source's **own** enumerable keys only. `for...in` previously walked the
+    source's prototype chain, which both leaked inherited properties into the
+    result and let `{"__proto__": …}` from `JSON.parse` replace `Object.prototype`.
+  - `setAtPath` refuses a path containing `__proto__`, `constructor` or
+    `prototype` and writes nothing, silently — the same way it already refused a
+    non-numeric index into an array. `getAtPath` is deliberately unchanged:
+    reading one of those hands back a prototype the caller could already reach
+    through any object it holds.
+- 2ab5593: Add `nullIfEmpty`, normalizing an object with no own enumerable property to
+  `null`. Useful against APIs that report "no value" as an empty object, so that
+  callers only have one absent form to test.
+- a493b4a: Add `parseNumberOrBigInt`, which reads a numeric literal out of text and widens
+  to `bigint` rather than rounding, and `bigIntIsSafeNumber`, the range test it
+  and `jsonMakeBigIntReplacerFunction` share.
+  
+  ```ts
+  parseNumberOrBigInt("42"); // 42
+  parseNumberOrBigInt("9007199254740993"); // 9007199254740993n
+  parseNumberOrBigInt("abc"); // null
+  ```
+  
+  Reach for it where a human wrote the value — an environment variable, a config
+  field, a CLI argument. `bigIntParse` remains the right call when the value must
+  be an integer or the radix is known and not spelled in the text; it reports a
+  malformed input by throwing rather than by returning `null`.

package/dist/big-int/from-bytes-be.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Decodes two's complement, big-endian bytes back into a `bigint` — the inverse
+ * of {@link bigIntToBytesBe}.
+ *
+ * The high bit of the first byte is the sign, so any width round-trips: `0xff`
+ * and `0xff_ff` both decode to `-1`. Reach for {@link bigIntFromBytesLe} when
+ * the least significant byte comes first.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param bytes - The encoding. An empty input decodes to zero.
+ */
+export declare function bigIntFromBytesBe(bytes: Uint8Array): bigint;
+//# sourceMappingURL=from-bytes-be.d.ts.map

package/dist/big-int/from-bytes-be.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-bytes-be.d.ts","sourceRoot":"","sources":["../../src/big-int/from-bytes-be.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQ3D"}

package/dist/big-int/from-bytes-be.js

@@ -0,0 +1,20 @@
+/**
+ * Decodes two's complement, big-endian bytes back into a `bigint` — the inverse
+ * of {@link bigIntToBytesBe}.
+ *
+ * The high bit of the first byte is the sign, so any width round-trips: `0xff`
+ * and `0xff_ff` both decode to `-1`. Reach for {@link bigIntFromBytesLe} when
+ * the least significant byte comes first.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param bytes - The encoding. An empty input decodes to zero.
+ */
+export function bigIntFromBytesBe(bytes) {
+    let value = 0n;
+    for (let index = 0; index < bytes.length; index++) {
+        value = (value << 8n) | BigInt(bytes[index]);
+    }
+    return BigInt.asIntN(bytes.length * 8, value);
+}
+//# sourceMappingURL=from-bytes-be.js.map

package/dist/big-int/from-bytes-be.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-bytes-be.js","sourceRoot":"","sources":["../../src/big-int/from-bytes-be.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IAClD,IAAI,KAAK,GAAG,EAAE,CAAC;IAEf,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/big-int/from-bytes-le.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Decodes two's complement, little-endian bytes back into a `bigint` — the
+ * inverse of {@link bigIntToBytesLe}.
+ *
+ * The high bit of the _last_ byte is the sign, so any width round-trips: `0xff`
+ * and `0xff_ff` both decode to `-1`. Reach for {@link bigIntFromBytesBe} when
+ * the most significant byte comes first, which is what wire formats usually
+ * specify.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param bytes - The encoding. An empty input decodes to zero.
+ */
+export declare function bigIntFromBytesLe(bytes: Uint8Array): bigint;
+//# sourceMappingURL=from-bytes-le.d.ts.map

package/dist/big-int/from-bytes-le.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-bytes-le.d.ts","sourceRoot":"","sources":["../../src/big-int/from-bytes-le.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQ3D"}

package/dist/big-int/from-bytes-le.js

@@ -0,0 +1,21 @@
+/**
+ * Decodes two's complement, little-endian bytes back into a `bigint` — the
+ * inverse of {@link bigIntToBytesLe}.
+ *
+ * The high bit of the _last_ byte is the sign, so any width round-trips: `0xff`
+ * and `0xff_ff` both decode to `-1`. Reach for {@link bigIntFromBytesBe} when
+ * the most significant byte comes first, which is what wire formats usually
+ * specify.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param bytes - The encoding. An empty input decodes to zero.
+ */
+export function bigIntFromBytesLe(bytes) {
+    let value = 0n;
+    for (let index = bytes.length - 1; index >= 0; index--) {
+        value = (value << 8n) | BigInt(bytes[index]);
+    }
+    return BigInt.asIntN(bytes.length * 8, value);
+}
+//# sourceMappingURL=from-bytes-le.js.map

package/dist/big-int/from-bytes-le.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-bytes-le.js","sourceRoot":"","sources":["../../src/big-int/from-bytes-le.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IAClD,IAAI,KAAK,GAAG,EAAE,CAAC;IAEf,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACxD,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/big-int/is-safe-number.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Check whether converting a `bigint` to a `number` is exact.
+ *
+ * True when the value lies within `Number.MIN_SAFE_INTEGER` and
+ * `Number.MAX_SAFE_INTEGER` inclusive, which is exactly the range where
+ * `Number(value)` round-trips. Outside it, `Number(value)` still succeeds and
+ * still returns a finite result — it just returns the wrong one — so a caller
+ * narrowing a `bigint` for presentation or arithmetic has to ask first.
+ *
+ * @example
+ * 	```ts
+ * 	bigIntIsSafeNumber(9007199254740991n); // true
+ * 	bigIntIsSafeNumber(9007199254740992n); // false
+ * 	```;
+ *
+ * @param value The value to check.
+ * @returns True if `Number(value)` loses nothing.
+ */
+export declare function bigIntIsSafeNumber(value: bigint): boolean;
+//# sourceMappingURL=is-safe-number.d.ts.map

package/dist/big-int/is-safe-number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-safe-number.d.ts","sourceRoot":"","sources":["../../src/big-int/is-safe-number.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/big-int/is-safe-number.js

@@ -0,0 +1,24 @@
+const MIN_SAFE_ = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE_ = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * Check whether converting a `bigint` to a `number` is exact.
+ *
+ * True when the value lies within `Number.MIN_SAFE_INTEGER` and
+ * `Number.MAX_SAFE_INTEGER` inclusive, which is exactly the range where
+ * `Number(value)` round-trips. Outside it, `Number(value)` still succeeds and
+ * still returns a finite result — it just returns the wrong one — so a caller
+ * narrowing a `bigint` for presentation or arithmetic has to ask first.
+ *
+ * @example
+ * 	```ts
+ * 	bigIntIsSafeNumber(9007199254740991n); // true
+ * 	bigIntIsSafeNumber(9007199254740992n); // false
+ * 	```;
+ *
+ * @param value The value to check.
+ * @returns True if `Number(value)` loses nothing.
+ */
+export function bigIntIsSafeNumber(value) {
+    return value >= MIN_SAFE_ && value <= MAX_SAFE_;
+}
+//# sourceMappingURL=is-safe-number.js.map

package/dist/big-int/is-safe-number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-safe-number.js","sourceRoot":"","sources":["../../src/big-int/is-safe-number.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC/C,OAAO,KAAK,IAAI,SAAS,IAAI,KAAK,IAAI,SAAS,CAAC;AACjD,CAAC"}

package/dist/big-int/to-bytes-be.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Encodes a `bigint` as two's complement, big-endian bytes.
+ *
+ * What Java's `BigInteger.toByteArray` and Python's `int.to_bytes` produce.
+ * Reach for {@link bigIntToBytesLe} when the least significant byte comes
+ * first, and for `@ac-kit/math-integer`'s `limb32`/`limb64` families when the
+ * digits feed arithmetic rather than a wire: those are little-endian, unsigned,
+ * and of fixed width.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param value - The value to encode. Zero encodes as a single `0x00`.
+ * @param byteLength - Fixed output width, sign-extended to fit. Omit for the
+ *   minimal encoding.
+ * @returns A fresh buffer, never empty.
+ * @throws {RangeError} When `byteLength` is too small to hold `value`.
+ */
+export declare function bigIntToBytesBe(value: bigint, byteLength?: number): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=to-bytes-be.d.ts.map

package/dist/big-int/to-bytes-be.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-bytes-be.d.ts","sourceRoot":"","sources":["../../src/big-int/to-bytes-be.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GACjB,UAAU,CAAC,WAAW,CAAC,CAqBzB"}

package/dist/big-int/to-bytes-be.js

@@ -0,0 +1,60 @@
+/**
+ * Encodes a `bigint` as two's complement, big-endian bytes.
+ *
+ * What Java's `BigInteger.toByteArray` and Python's `int.to_bytes` produce.
+ * Reach for {@link bigIntToBytesLe} when the least significant byte comes
+ * first, and for `@ac-kit/math-integer`'s `limb32`/`limb64` families when the
+ * digits feed arithmetic rather than a wire: those are little-endian, unsigned,
+ * and of fixed width.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param value - The value to encode. Zero encodes as a single `0x00`.
+ * @param byteLength - Fixed output width, sign-extended to fit. Omit for the
+ *   minimal encoding.
+ * @returns A fresh buffer, never empty.
+ * @throws {RangeError} When `byteLength` is too small to hold `value`.
+ */
+export function bigIntToBytesBe(value, byteLength) {
+    const minimal = toMinimalBytes(value);
+    if (byteLength === undefined) {
+        return minimal;
+    }
+    if (minimal.length > byteLength) {
+        throw new RangeError(`bigIntToBytesBe: ${value} needs ${minimal.length} bytes, not ${byteLength}`);
+    }
+    const out = new Uint8Array(byteLength);
+    const padding = byteLength - minimal.length;
+    // Sign extension, not zero padding: a negative value's high bytes are 0xff.
+    out.fill(value < 0n ? 0xff : 0x00, 0, padding);
+    out.set(minimal, padding);
+    return out;
+}
+function toMinimalBytes(value) {
+    if (value === 0n) {
+        return new Uint8Array([0x00]);
+    }
+    const negative = value < 0n;
+    // For a negative, encode |value| - 1 and invert: that is two's complement
+    // without ever needing to know the final width up front.
+    let remaining = negative ? -value - 1n : value;
+    const digits = [];
+    while (remaining > 0n) {
+        digits.unshift(Number(remaining & 0xffn));
+        remaining >>= 8n;
+    }
+    if (negative) {
+        for (let index = 0; index < digits.length; index++) {
+            digits[index] = ~digits[index] & 0xff;
+        }
+        // A leading byte without its high bit set would read back as positive.
+        if (digits.length === 0 || (digits[0] & 0x80) === 0) {
+            digits.unshift(0xff);
+        }
+    }
+    else if ((digits[0] & 0x80) !== 0) {
+        digits.unshift(0x00);
+    }
+    return new Uint8Array(digits);
+}
+//# sourceMappingURL=to-bytes-be.js.map

package/dist/big-int/to-bytes-be.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-bytes-be.js","sourceRoot":"","sources":["../../src/big-int/to-bytes-be.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC9B,KAAa,EACb,UAAmB;IAEnB,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAEtC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,UAAU,CACnB,oBAAoB,KAAK,UAAU,OAAO,CAAC,MAAM,eAAe,UAAU,EAAE,CAC5E,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAE5C,4EAA4E;IAC5E,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IAC/C,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAE1B,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACpC,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QAClB,OAAO,IAAI,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,GAAG,EAAE,CAAC;IAC5B,0EAA0E;IAC1E,yDAAyD;IACzD,IAAI,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/C,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,OAAO,SAAS,GAAG,EAAE,EAAE,CAAC;QACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC;QAC1C,SAAS,KAAK,EAAE,CAAC;IAClB,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACd,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;YACpD,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAE,GAAG,IAAI,CAAC;QACxC,CAAC;QAED,uEAAuE;QACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACF,CAAC;SAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC"}

package/dist/big-int/to-bytes-le.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Encodes a `bigint` as two's complement, little-endian bytes.
+ *
+ * The byte order native to x86 and ARM, and what Python's `int.to_bytes(…,
+ * "little")` produces. Reach for {@link bigIntToBytesBe} when the most
+ * significant byte comes first, which is what wire formats usually specify, and
+ * for `@ac-kit/math-integer`'s `limb32`/`limb64` families when the digits feed
+ * arithmetic rather than a buffer: those are wider, unsigned, and of fixed
+ * width.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param value - The value to encode. Zero encodes as a single `0x00`. @param
+ * byteLength - Fixed output width, sign-extended to fit. Omit for the minimal
+ * encoding. @returns A fresh buffer, never empty. @throws {RangeError} When
+ * `byteLength` is too small to hold `value`.
+ */
+export declare function bigIntToBytesLe(value: bigint, byteLength?: number): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=to-bytes-le.d.ts.map

package/dist/big-int/to-bytes-le.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-bytes-le.d.ts","sourceRoot":"","sources":["../../src/big-int/to-bytes-le.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GACjB,UAAU,CAAC,WAAW,CAAC,CAEzB"}

package/dist/big-int/to-bytes-le.js

@@ -0,0 +1,22 @@
+import { bigIntToBytesBe } from "./to-bytes-be.js";
+/**
+ * Encodes a `bigint` as two's complement, little-endian bytes.
+ *
+ * The byte order native to x86 and ARM, and what Python's `int.to_bytes(…,
+ * "little")` produces. Reach for {@link bigIntToBytesBe} when the most
+ * significant byte comes first, which is what wire formats usually specify, and
+ * for `@ac-kit/math-integer`'s `limb32`/`limb64` families when the digits feed
+ * arithmetic rather than a buffer: those are wider, unsigned, and of fixed
+ * width.
+ *
+ * Time complexity: O(n) in the byte count.
+ *
+ * @param value - The value to encode. Zero encodes as a single `0x00`. @param
+ * byteLength - Fixed output width, sign-extended to fit. Omit for the minimal
+ * encoding. @returns A fresh buffer, never empty. @throws {RangeError} When
+ * `byteLength` is too small to hold `value`.
+ */
+export function bigIntToBytesLe(value, byteLength) {
+    return bigIntToBytesBe(value, byteLength).reverse();
+}
+//# sourceMappingURL=to-bytes-le.js.map

package/dist/big-int/to-bytes-le.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-bytes-le.js","sourceRoot":"","sources":["../../src/big-int/to-bytes-le.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC9B,KAAa,EACb,UAAmB;IAEnB,OAAO,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;AACrD,CAAC"}

package/dist/buffer/bytes-combine.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Applies `combine` to each octet pair of two equal-length arrays.
+ *
+ * The result of `combine` is masked to one octet. Pairing stops at the shorter
+ * array only when lengths are allowed to differ, which they are not here: a
+ * bitwise operation over mismatched widths has no meaning, so it throws rather
+ * than silently truncating.
+ *
+ * Complexity: O(n) time and O(n) memory in the input length.
+ *
+ * @param a The left octets.
+ * @param b The right octets.
+ * @param combine Called with each octet pair and its index.
+ * @returns A new array of the same length.
+ * @throws RangeError When the two arrays differ in length.
+ */
+export declare function bytesCombine(a: Uint8Array, b: Uint8Array, combine: (left: number, right: number, index: number) => number): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=bytes-combine.d.ts.map

package/dist/buffer/bytes-combine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes-combine.d.ts","sourceRoot":"","sources":["../../src/buffer/bytes-combine.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC3B,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAC7D,UAAU,CAAC,WAAW,CAAC,CASzB"}

package/dist/buffer/bytes-combine.js

@@ -0,0 +1,25 @@
+import { bytesMap } from "./bytes-map.js";
+/**
+ * Applies `combine` to each octet pair of two equal-length arrays.
+ *
+ * The result of `combine` is masked to one octet. Pairing stops at the shorter
+ * array only when lengths are allowed to differ, which they are not here: a
+ * bitwise operation over mismatched widths has no meaning, so it throws rather
+ * than silently truncating.
+ *
+ * Complexity: O(n) time and O(n) memory in the input length.
+ *
+ * @param a The left octets.
+ * @param b The right octets.
+ * @param combine Called with each octet pair and its index.
+ * @returns A new array of the same length.
+ * @throws RangeError When the two arrays differ in length.
+ */
+export function bytesCombine(a, b, combine) {
+    if (a.length !== b.length) {
+        throw new RangeError(`cannot combine ${a.length} octets with ${b.length} octets`);
+    }
+    // Non-null: `index` runs over `a`'s length, and `b` has been checked equal.
+    return bytesMap(a, (byte, index) => combine(byte, b[index], index));
+}
+//# sourceMappingURL=bytes-combine.js.map

package/dist/buffer/bytes-combine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes-combine.js","sourceRoot":"","sources":["../../src/buffer/bytes-combine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAC3B,CAAa,EACb,CAAa,EACb,OAA+D;IAE/D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,UAAU,CACnB,kBAAkB,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,MAAM,SAAS,CAC3D,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,OAAO,QAAQ,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAE,EAAE,KAAK,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/buffer/bytes-map.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Applies `map` to every octet of `bytes`, returning a new array.
+ *
+ * The result of `map` is masked to one octet, so a caller may write `~byte`
+ * without restating `& 0xff`.
+ *
+ * Complexity: O(n) time and O(n) memory in the input length.
+ *
+ * @param bytes The source octets.
+ * @param map Called with each octet and its index.
+ * @returns A new array of the same length.
+ */
+export declare function bytesMap(bytes: Uint8Array, map: (byte: number, index: number) => number): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=bytes-map.d.ts.map

package/dist/buffer/bytes-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes-map.d.ts","sourceRoot":"","sources":["../../src/buffer/bytes-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACvB,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAC1C,UAAU,CAAC,WAAW,CAAC,CASzB"}

package/dist/buffer/bytes-map.js

@@ -0,0 +1,21 @@
+/**
+ * Applies `map` to every octet of `bytes`, returning a new array.
+ *
+ * The result of `map` is masked to one octet, so a caller may write `~byte`
+ * without restating `& 0xff`.
+ *
+ * Complexity: O(n) time and O(n) memory in the input length.
+ *
+ * @param bytes The source octets.
+ * @param map Called with each octet and its index.
+ * @returns A new array of the same length.
+ */
+export function bytesMap(bytes, map) {
+    const result = new Uint8Array(bytes.length);
+    for (let index = 0; index < bytes.length; index++) {
+        // Non-null: `index` runs over the source array's own length.
+        result[index] = map(bytes[index], index) & 0xff;
+    }
+    return result;
+}
+//# sourceMappingURL=bytes-map.js.map

package/dist/buffer/bytes-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes-map.js","sourceRoot":"","sources":["../../src/buffer/bytes-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CACvB,KAAiB,EACjB,GAA4C;IAE5C,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,6DAA6D;QAC7D,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAE,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IAClD,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/buffer/text/next-utf8-boundary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Index of the first UTF-8 character boundary at or after `index`.
+ *
+ * Slicing a UTF-8 buffer at an arbitrary offset can land inside a multi-byte
+ * sequence, whose orphaned tail decodes to a leading U+FFFD. Moving the offset
+ * forward to a boundary drops the partial character instead.
+ *
+ * Runs in O(1) on valid input — a sequence is at most four bytes long, so at
+ * most three continuation bytes are skipped — and in O(n) on the length of a
+ * malformed continuation run. Allocates nothing.
+ *
+ * @param bytes - UTF-8 encoded bytes.
+ * @param index - Offset to align. Negative values align to `0`.
+ * @returns The aligned offset, within `[0, bytes.length]`.
+ */
+export declare function nextUtf8Boundary(bytes: Uint8Array, index: number): number;
+//# sourceMappingURL=next-utf8-boundary.d.ts.map

package/dist/buffer/text/next-utf8-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-utf8-boundary.d.ts","sourceRoot":"","sources":["../../../src/buffer/text/next-utf8-boundary.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWzE"}

package/dist/buffer/text/next-utf8-boundary.js

@@ -0,0 +1,27 @@
+// A UTF-8 continuation byte is `0b10xxxxxx`; every other byte starts a character.
+const CONTINUATION_MASK_ = 192;
+const CONTINUATION_BITS_ = 128;
+/**
+ * Index of the first UTF-8 character boundary at or after `index`.
+ *
+ * Slicing a UTF-8 buffer at an arbitrary offset can land inside a multi-byte
+ * sequence, whose orphaned tail decodes to a leading U+FFFD. Moving the offset
+ * forward to a boundary drops the partial character instead.
+ *
+ * Runs in O(1) on valid input — a sequence is at most four bytes long, so at
+ * most three continuation bytes are skipped — and in O(n) on the length of a
+ * malformed continuation run. Allocates nothing.
+ *
+ * @param bytes - UTF-8 encoded bytes.
+ * @param index - Offset to align. Negative values align to `0`.
+ * @returns The aligned offset, within `[0, bytes.length]`.
+ */
+export function nextUtf8Boundary(bytes, index) {
+    let boundary = Math.max(0, index);
+    while (boundary < bytes.length &&
+        (bytes[boundary] & CONTINUATION_MASK_) === CONTINUATION_BITS_) {
+        boundary++;
+    }
+    return Math.min(boundary, bytes.length);
+}
+//# sourceMappingURL=next-utf8-boundary.js.map

package/dist/buffer/text/next-utf8-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-utf8-boundary.js","sourceRoot":"","sources":["../../../src/buffer/text/next-utf8-boundary.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,kBAAkB,GAAG,GAAW,CAAC;AACvC,MAAM,kBAAkB,GAAG,GAAW,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB,EAAE,KAAa;IAChE,IAAI,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAElC,OACC,QAAQ,GAAG,KAAK,CAAC,MAAM;QACvB,CAAC,KAAK,CAAC,QAAQ,CAAE,GAAG,kBAAkB,CAAC,KAAK,kBAAkB,EAC7D,CAAC;QACF,QAAQ,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC"}

package/dist/guards/has-object-prototype.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Check whether a value's own prototype is `Object.prototype` or `null`.
+ *
+ * Strictly narrower than `isPojo`, which follows the whole prototype chain and
+ * so also accepts `Object.create({})`. Both ask "is this a data bag"; this one
+ * refuses a bag that inherits from another bag.
+ *
+ * Reach for it when the answer decides how a value is _rebuilt_ rather than how
+ * it is read — a traversal that rewrites a node into a fresh `{}`, a serializer
+ * choosing between an object form and a tagged form. Inherited keys are lost by
+ * such a rebuild, so a chain-following test would claim a fidelity the output
+ * does not have. When you only mean to read own keys, `isPojo` is the more
+ * forgiving question; see `isObject` for the whole family.
+ *
+ * @example
+ * 	```ts
+ * 	hasObjectPrototype({}); // true
+ * 	hasObjectPrototype(Object.create(null)); // true
+ * 	hasObjectPrototype(Object.create({})); // false
+ * 	hasObjectPrototype(new Date()); // false
+ * 	```;
+ *
+ * @param value The object to check.
+ * @returns True if nothing sits between the value and `Object.prototype`.
+ */
+export declare function hasObjectPrototype(value: object): boolean;
+//# sourceMappingURL=has-object-prototype.d.ts.map

package/dist/guards/has-object-prototype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"has-object-prototype.d.ts","sourceRoot":"","sources":["../../src/guards/has-object-prototype.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD"}

package/dist/guards/has-object-prototype.js

@@ -0,0 +1,30 @@
+/**
+ * Check whether a value's own prototype is `Object.prototype` or `null`.
+ *
+ * Strictly narrower than `isPojo`, which follows the whole prototype chain and
+ * so also accepts `Object.create({})`. Both ask "is this a data bag"; this one
+ * refuses a bag that inherits from another bag.
+ *
+ * Reach for it when the answer decides how a value is _rebuilt_ rather than how
+ * it is read — a traversal that rewrites a node into a fresh `{}`, a serializer
+ * choosing between an object form and a tagged form. Inherited keys are lost by
+ * such a rebuild, so a chain-following test would claim a fidelity the output
+ * does not have. When you only mean to read own keys, `isPojo` is the more
+ * forgiving question; see `isObject` for the whole family.
+ *
+ * @example
+ * 	```ts
+ * 	hasObjectPrototype({}); // true
+ * 	hasObjectPrototype(Object.create(null)); // true
+ * 	hasObjectPrototype(Object.create({})); // false
+ * 	hasObjectPrototype(new Date()); // false
+ * 	```;
+ *
+ * @param value The object to check.
+ * @returns True if nothing sits between the value and `Object.prototype`.
+ */
+export function hasObjectPrototype(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+//# sourceMappingURL=has-object-prototype.js.map

package/dist/guards/has-object-prototype.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"has-object-prototype.js","sourceRoot":"","sources":["../../src/guards/has-object-prototype.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}