Upload via GUI (7543 Dateien)

2026-10-22 07:02:28 +00:00
parent 42fb8dfe9b
commit b2314f6fe6
50 changed files with 4466 additions and 0 deletions
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2026 Peculiar Ventures, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,299 @@
+# @peculiar/utils
+
+[![npm version](https://img.shields.io/npm/v/%40peculiar%2Futils.svg)](https://www.npmjs.com/package/@peculiar/utils)
+[![Test](https://github.com/PeculiarVentures/pvtsutils/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/PeculiarVentures/pvtsutils/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/github/PeculiarVentures/pvtsutils/badge.svg?branch=master)](https://coveralls.io/github/PeculiarVentures/pvtsutils?branch=master)
+[![License: MIT](https://img.shields.io/github/license/PeculiarVentures/pvtsutils.svg)](https://github.com/PeculiarVentures/pvtsutils/blob/master/LICENSE)
+
+Modern byte, text, converter registry, and PEM utilities for TypeScript projects.
+
+The package is designed around a modular v2 API:
+
+- multi-entry exports for tree-shake-friendly imports;
+- `encode` and `decode` terminology;
+- an extensible runtime converter registry;
+- generic PEM helpers without PKI-specific parsing;
+- a legacy compatibility layer for historical `pvtsutils` consumers.
+
+## Install
+
+```bash
+npm install @peculiar/utils
+```
+
+## Entry Points
+
+```ts
+import { bytes } from "@peculiar/utils";
+import { hex, base64, base64url } from "@peculiar/utils/encoding";
+import { pem } from "@peculiar/utils/pem";
+import { convert, createConverterRegistry, defaultConverters } from "@peculiar/utils/converters";
+import { Convert } from "@peculiar/utils/legacy";
+```
+
+## Bytes Helpers
+
+`@peculiar/utils/bytes` stays focused on stateless byte sequence utilities. It does not include stateful readers, writers, ASN.1 parsing, PDF parsing, or other structured binary readers. For structured binary parsing, use a dedicated binary reader package.
+
+```ts
+import { bytes } from "@peculiar/utils";
+
+const offset = bytes.indexOf(new Uint8Array([0x25, 0x25, 0x45, 0x4f, 0x46]), "%%EOF", {
+ encoding: "ascii",
+});
+
+const suffix = bytes.endsWith(new Uint8Array([0x25, 0x25, 0x45, 0x4f, 0x46]), "%%EOF", {
+ encoding: "ascii",
+});
+```
+
+### Find `startxref` In A PDF Tail
+
+```ts
+import { lastIndexOf } from "@peculiar/utils/bytes";
+
+const tailStart = Math.max(0, pdf.byteLength - 4096);
+
+const offset = lastIndexOf(pdf, "startxref", {
+ encoding: "ascii",
+ start: pdf.byteLength,
+ end: tailStart,
+});
+
+if (offset === -1) {
+ throw new Error("PDF startxref marker not found");
+}
+```
+
+### Find `startxref` Via `tail`
+
+```ts
+import { lastIndexOf, tail } from "@peculiar/utils/bytes";
+
+const pdfTail = tail(pdf, 4096);
+
+const localOffset = lastIndexOf(pdfTail, "startxref", {
+ encoding: "ascii",
+});
+
+const offset =
+ localOffset === -1
+    ? -1
+    : pdf.byteLength - pdfTail.byteLength + localOffset;
+```
+
+### Check Prefixes And Suffixes
+
+```ts
+import { bytes } from "@peculiar/utils";
+
+bytes.startsWith(data, "-----BEGIN", { encoding: "ascii" });
+bytes.endsWith(data, "%%EOF", { encoding: "ascii" });
+```
+
+### Compare Byte Sequences
+
+```ts
+import { bytes } from "@peculiar/utils";
+
+const result = bytes.compare(a, b);
+
+if (result === 0) {
+ console.log("equal");
+}
+```
+
+## Convert API
+
+The default `convert` facade is a convenience singleton backed by the built-in registry.
+
+```ts
+import { convert } from "@peculiar/utils/converters";
+
+const bytes = convert.decode("base64", "AQID");
+const text = convert.encode("hex", bytes, { case: "upper" });
+```
+
+Deprecated `convert.to(...)` and `convert.from(...)` aliases are still available for temporary migration, but the primary v2 API is `encode` and `decode`.
+
+## Transcode
+
+Direct text-to-text transcoding goes through the registry without a manual intermediate step.
+
+```ts
+import { convert } from "@peculiar/utils/converters";
+import { hex } from "@peculiar/utils/encoding";
+
+const pemText = convert.transcode("AQID", {
+ from: "base64",
+ to: "pem",
+ toOptions: {
+  label: "CERTIFICATE",
+ },
+});
+
+const hexText = convert.transcode(pemText, {
+ from: "pem",
+ fromOptions: { label: "CERTIFICATE" },
+ to: "hex",
+ toOptions: hex.formats.colonUpper,
+});
+```
+
+There is intentionally no chain API.
+
+## Hex Formatting
+
+The `hex` codec accepts common input styles and can format output explicitly.
+
+```ts
+import { hex } from "@peculiar/utils/encoding";
+
+hex.decode("0102030405060708090a0b0c");
+hex.decode("01020304 05060708 090a0b0c");
+hex.decode("01:02:03:04:05:06:07:08:09:0A:0B:0C");
+hex.decode("0x0102030405060708090a0b0c");
+
+hex.encode(new Uint8Array([1, 2, 3, 4]), hex.formats.colonUpper);
+hex.encode(new Uint8Array([1, 2, 3, 4]), {
+ prefix: "0x",
+ group: {
+  size: 2,
+  separator: " ",
+ },
+});
+```
+
+Available presets:
+
+- `hex.formats.compact`
+- `hex.formats.upper`
+- `hex.formats.colon`
+- `hex.formats.colonUpper`
+- `hex.formats.groupsOf4`
+- `hex.formats.prefixed`
+
+## Preserve Formatting
+
+Use `parse` and `format` when you want to keep the original visual style of a hex string.
+
+```ts
+import { hex } from "@peculiar/utils/encoding";
+
+const parsed = hex.parse("01:02:03:04:05:06");
+
+parsed.bytes;
+parsed.format;
+parsed.normalized;
+
+const updated = hex.format(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff]), parsed.format);
+```
+
+The same capabilities are available through the registry facade:
+
+```ts
+import { convert } from "@peculiar/utils/converters";
+
+const parsed = convert.parse("hex", "01:02:03:04");
+const formatted = convert.format("hex", new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd]), parsed.format);
+```
+
+## PEM Helpers
+
+PEM support stays generic. The package does not parse ASN.1, validate PKI semantics, or handle encrypted PEM containers.
+
+```ts
+import { pem } from "@peculiar/utils/pem";
+
+const text = pem.encode("CERTIFICATE", new Uint8Array([1, 2, 3]));
+const blocks = pem.decode(text);
+const block = pem.find(text, "CERTIFICATE");
+const matches = pem.findAll(text, "CERTIFICATE");
+
+const bundle = pem.encodeMany([
+ { label: "CERTIFICATE", data: new Uint8Array([1, 2, 3]) },
+ { label: "PRIVATE KEY", data: new Uint8Array([4, 5, 6]) },
+]);
+```
+
+## Safe Decode And Detection
+
+```ts
+import { convert } from "@peculiar/utils/converters";
+
+const result = convert.tryDecode("hex", "01:02:03");
+
+if (result.ok) {
+ console.log(result.bytes);
+} else {
+ console.error(result.error);
+}
+
+const candidates = convert.detect("-----BEGIN DATA-----\nAQID\n-----END DATA-----\n", {
+ formats: ["pem", "base64", "hex"],
+});
+```
+
+## Custom Registries
+
+Applications can create isolated registries instead of mutating global state.
+
+```ts
+import { createConverterRegistry, defaultConverters } from "@peculiar/utils/converters";
+
+const registry = createConverterRegistry(defaultConverters);
+
+registry.register({
+ name: "base58btc",
+ aliases: ["b58"],
+ encode(data) {
+  return base58btcEncode(data);
+ },
+ decode(text) {
+  return base58btcDecode(text);
+ },
+});
+```
+
+Name and alias conflicts throw by default. Use `{ override: true }` only when replacement is intentional.
+
+## Typed Converter Options
+
+Built-in converters expose typed options through the registry facade.
+
+```ts
+import { convert } from "@peculiar/utils/converters";
+
+convert.encode("hex", new Uint8Array([1, 2, 3]), {
+ case: "upper",
+});
+```
+
+Wrong options are rejected by TypeScript:
+
+```ts
+convert.encode("hex", new Uint8Array([1, 2, 3]), {
+ label: "CERTIFICATE",
+});
+```
+
+Custom converters can extend the options map via module augmentation:
+
+```ts
+declare module "@peculiar/utils/converters" {
+ interface ConverterOptionsMap {
+  base58btc: {
+   encode: Base58EncodeOptions;
+   decode: Base58DecodeOptions;
+  };
+ }
+}
+```
+
+## Legacy Compatibility
+
+The old `pvtsutils`-style surface is preserved under the legacy entry point.
+
+```ts
+import { BufferSourceConverter, Convert, assign, combine, isEqual } from "@peculiar/utils/legacy";
+```
@@ -0,0 +1,52 @@
+import type { BufferSourceLike } from "../bytes/index.js";
+import { type BufferEncoding } from "../converters/index.js";
+import type { Utf16Options } from "../encoding/utf16.js";
+/** Legacy text encodings accepted by the deprecated facade. */
+export type TextEncoding = "ascii" | "utf8" | "utf16" | "utf16be" | "utf16le" | "usc2";
+/**
+ * Legacy converter facade that mirrors the historical API surface.
+ * @deprecated Use the camelCase `convert` object or specific encoding modules instead.
+ */
+export declare class Convert {
+    /** Default UTF-8 encoding used by the legacy facade. */
+    static DEFAULT_UTF8_ENCODING: TextEncoding;
+    /** Checks whether the input is hexadecimal text. */
+    static isHex(data: unknown): data is string;
+    /** Checks whether the input is Base64 text. */
+    static isBase64(data: unknown): data is string;
+    /** Checks whether the input is Base64Url text. */
+    static isBase64Url(data: unknown): data is string;
+    /** Converts buffer data to text. */
+    static ToString(buffer: BufferSourceLike, enc?: BufferEncoding): string;
+    /** Converts text to bytes. */
+    static FromString(str: string, enc?: BufferEncoding): ArrayBufferLike;
+    /** Encodes bytes as Base64 text. */
+    static ToBase64(buffer: BufferSourceLike): string;
+    /** Decodes Base64 text into bytes. */
+    static FromBase64(base64: string): ArrayBufferLike;
+    /** Decodes Base64Url text into bytes. */
+    static FromBase64Url(base64url: string): ArrayBufferLike;
+    /** Encodes bytes as Base64Url text. */
+    static ToBase64Url(data: BufferSourceLike): string;
+    /** Converts UTF-8 or UTF-16 text to bytes. */
+    static FromUtf8String(text: string, encoding?: TextEncoding): ArrayBufferLike;
+    /** Converts bytes to UTF-8 or UTF-16 text. */
+    static ToUtf8String(buffer: BufferSourceLike, encoding?: TextEncoding): string;
+    /** Decodes binary text into bytes. */
+    static FromBinary(text: string): ArrayBufferLike;
+    /** Encodes bytes as binary text. */
+    static ToBinary(buffer: BufferSourceLike): string;
+    /** Encodes bytes as hexadecimal text. */
+    static ToHex(buffer: BufferSourceLike): string;
+    /** Decodes hexadecimal text into bytes. */
+    static FromHex(hexString: string): ArrayBufferLike;
+    /** Converts UTF-16 bytes into text. */
+    static ToUtf16String(buffer: BufferSourceLike, littleEndian?: boolean): string;
+    /** Converts UTF-16 text into bytes. */
+    static FromUtf16String(text: string, littleEndian?: boolean): ArrayBufferLike;
+    protected static Base64Padding(base64: string): string;
+    /** Normalizes whitespace in Base64-style text. */
+    static formatString(data: string): string;
+}
+/** Legacy text encoding aliases re-exported for compatibility. */
+export type { BufferEncoding, Utf16Options };
@@ -0,0 +1,16 @@
+import type { BufferSourceLike } from "../bytes/index.js";
+/**
+ * Assigns own properties from source objects into the target object.
+ * @deprecated Prefer object spread or Object.assign.
+ */
+export declare function assign<T extends object>(target: T, ...sources: (Partial<T> | undefined | null)[]): T;
+/**
+ * Concatenates buffer sources into a single ArrayBuffer.
+ * @deprecated Use `concat` from `@peculiar/utils/bytes` instead.
+ */
+export declare function combine(...buf: BufferSourceLike[]): ArrayBufferLike;
+/**
+ * Compares two buffer sources for equality.
+ * @deprecated Use `equal` from `@peculiar/utils/bytes` instead.
+ */
+export declare function isEqual(bytes1: BufferSourceLike, bytes2: BufferSourceLike): boolean;
@@ -0,0 +1,5 @@
+/** Barrel export for the deprecated compatibility layer. */
+export { BufferSourceConverter } from "./buffer-source-converter.js";
+export { Convert } from "./convert.js";
+export type { BufferEncoding, TextEncoding } from "./convert.js";
+export { assign, combine, isEqual } from "./functions.js";
@@ -0,0 +1,3 @@
+/** Barrel export for PEM helpers, codecs, and related types. */
+export type { PemBlock, PemCodec, PemDecodeOptions, PemEncodeBlock, PemEncodeOptions, PemFormat } from "./types.js";
+export { decode, decodeFirst, encode, encodeMany, find, findAll, format, parse, pem, pemConverter } from "./pem.js";
@@ -0,0 +1,34 @@
+import type { BufferSourceLike } from "../bytes/index.js";
+import type { ParsedBytes, Converter } from "../converters/types.js";
+import type { PemBlock, PemDecodeOptions, PemEncodeBlock, PemEncodeOptions, PemFormat } from "./types.js";
+/** Encodes buffer data into a PEM block. */
+export declare function encode(label: string, data: BufferSourceLike, options?: PemEncodeOptions): string;
+/** Encodes multiple PEM blocks into one PEM bundle. */
+export declare function encodeMany(blocks: readonly PemEncodeBlock[], options?: PemEncodeOptions): string;
+/** Decodes PEM text into the contained blocks. */
+export declare function decode(text: string, options?: PemDecodeOptions): PemBlock[];
+/** Finds the first PEM block with the requested label. */
+export declare function find(text: string, label: string): PemBlock | undefined;
+/** Finds all PEM blocks with the requested label. */
+export declare function findAll(text: string, label: string): PemBlock[];
+/** Decodes the first matching PEM block. */
+export declare function decodeFirst(text: string, label?: string): Uint8Array;
+/** Parses the first matching PEM block and preserves its formatting metadata. */
+export declare function parse(text: string, options?: PemDecodeOptions): ParsedBytes<PemFormat>;
+/** Formats bytes with preserved PEM metadata. */
+export declare function format(data: BufferSourceLike, value: PemFormat): string;
+/** PEM codec helpers. */
+export declare const pem: {
+    readonly decode: typeof decode;
+    readonly decodeFirst: typeof decodeFirst;
+    readonly encode: typeof encode;
+    readonly encodeMany: typeof encodeMany;
+    readonly find: typeof find;
+    readonly findAll: typeof findAll;
+    readonly format: typeof format;
+    readonly parse: typeof parse;
+};
+/** Converter wrapper for PEM text. */
+export declare const pemConverter: Converter<PemEncodeOptions & {
+    label: string;
+}, PemDecodeOptions, PemFormat>;
@@ -0,0 +1,48 @@
+import type { BufferSourceLike } from "../bytes/index.js";
+import type { ParsedBytes } from "../converters/types.js";
+/** Represents a decoded PEM block with label, data, and optional headers. */
+export interface PemBlock {
+    readonly label: string;
+    readonly data: Uint8Array;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Options that control PEM encoding. */
+export interface PemEncodeOptions {
+    lineLength?: number;
+    newline?: "\n" | "\r\n";
+    headers?: Readonly<Record<string, string>>;
+}
+/** Options that control PEM decoding. */
+export interface PemDecodeOptions {
+    label?: string;
+    strict?: boolean;
+}
+/** Format metadata that can be reused to re-encode PEM text. */
+export interface PemFormat extends PemEncodeOptions {
+    readonly label: string;
+}
+/** Input block used by multi-block PEM encoding helpers. */
+export interface PemEncodeBlock {
+    readonly label: string;
+    readonly data: BufferSourceLike;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Encodes and decodes PEM blocks. */
+export interface PemCodec {
+    /** Encodes a buffer source into a PEM block. */
+    encode(label: string, data: BufferSourceLike, options?: PemEncodeOptions): string;
+    /** Encodes multiple PEM blocks into a single string. */
+    encodeMany(blocks: readonly PemEncodeBlock[], options?: PemEncodeOptions): string;
+    /** Decodes PEM text into blocks. */
+    decode(text: string, options?: PemDecodeOptions): PemBlock[];
+    /** Decodes the first matching PEM block. */
+    decodeFirst(text: string, label?: string): Uint8Array;
+    /** Finds the first PEM block with the requested label. */
+    find(text: string, label: string): PemBlock | undefined;
+    /** Finds all PEM blocks with the requested label. */
+    findAll(text: string, label: string): PemBlock[];
+    /** Parses the first matching PEM block and preserves the detected formatting. */
+    parse(text: string, options?: PemDecodeOptions): ParsedBytes<PemFormat>;
+    /** Formats bytes with previously detected PEM metadata. */
+    format(data: BufferSourceLike, format: PemFormat): string;
+}
@@ -0,0 +1,111 @@
+{
+  "name": "@peculiar/utils",
+  "version": "2.0.3",
+  "description": "Modern byte, encoding, converter registry, and PEM utilities for TypeScript projects.",
+  "type": "module",
+  "main": "./build/cjs/index.js",
+  "module": "./build/esm/index.js",
+  "types": "./build/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/types/index.d.ts",
+      "import": "./build/esm/index.js",
+      "require": "./build/cjs/index.js"
+    },
+    "./bytes": {
+      "types": "./build/types/bytes/index.d.ts",
+      "import": "./build/esm/bytes/index.js",
+      "require": "./build/cjs/bytes/index.js"
+    },
+    "./encoding": {
+      "types": "./build/types/encoding/index.d.ts",
+      "import": "./build/esm/encoding/index.js",
+      "require": "./build/cjs/encoding/index.js"
+    },
+    "./encoding/*": {
+      "types": "./build/types/encoding/*.d.ts",
+      "import": "./build/esm/encoding/*.js",
+      "require": "./build/cjs/encoding/*.js"
+    },
+    "./converters": {
+      "types": "./build/types/converters/index.d.ts",
+      "import": "./build/esm/converters/index.js",
+      "require": "./build/cjs/converters/index.js"
+    },
+    "./pem": {
+      "types": "./build/types/pem/index.d.ts",
+      "import": "./build/esm/pem/index.js",
+      "require": "./build/cjs/pem/index.js"
+    },
+    "./legacy": {
+      "types": "./build/types/legacy/index.d.ts",
+      "import": "./build/esm/legacy/index.js",
+      "require": "./build/cjs/legacy/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build/cjs/**/*.js",
+    "build/cjs/package.json",
+    "build/esm/**/*.js",
+    "build/types/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "clear": "rimraf build",
+    "rebuild": "npm run clear && npm run build",
+    "build": "node scripts/prune-legacy-build-outputs.mjs && tsc -p tsconfig.build.types.json && tsc -p tsconfig.build.esm.json && tsc -p tsconfig.build.cjs.json && node scripts/write-cjs-package-json.mjs",
+    "prepack": "npm run build",
+    "publish:manual": "npm run check && npm run build && npm publish --ignore-scripts",
+    "lint:check": "eslint . --fix-dry-run",
+    "check": "npm run lint:check && tsc --noEmit && npm test",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "keywords": [
+    "typescript",
+    "utils",
+    "buffer",
+    "bytes",
+    "convert",
+    "encoding",
+    "base64",
+    "base64url",
+    "hex",
+    "utf8",
+    "utf16",
+    "pem",
+    "pki",
+    "peculiar"
+  ],
+  "author": "PeculiarVentures",
+  "contributors": [
+    "Miroshin Stepan<microshine@mail.ru>"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PeculiarVentures/pvtsutils"
+  },
+  "bugs": {
+    "url": "https://github.com/PeculiarVentures/pvtsutils/issues"
+  },
+  "homepage": "https://github.com/PeculiarVentures/pvtsutils#readme",
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@peculiar/eslint-config-base": "^0.2.9",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}