@synet/encoder 1.0.0

package/dist/functions.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Pure Encoding Functions - Serverless Ready
+ *
+ * Simple, stateless functions for encoding/decoding operations.
+ * These throw on error (simple operations) following Doctrine #14.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBase64 = encodeBase64;
+exports.decodeBase64 = decodeBase64;
+exports.encodeBase64URL = encodeBase64URL;
+exports.decodeBase64URL = decodeBase64URL;
+exports.encodeHex = encodeHex;
+exports.decodeHex = decodeHex;
+exports.encodeURIString = encodeURIString;
+exports.decodeURIString = decodeURIString;
+exports.encodeASCII = encodeASCII;
+exports.decodeASCII = decodeASCII;
+exports.encode = encode;
+exports.decode = decode;
+exports.detectFormat = detectFormat;
+exports.validateFormat = validateFormat;
+exports.chain = chain;
+exports.reverseChain = reverseChain;
+/**
+ * Encode string to Base64
+ */
+function encodeBase64(data) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(data, 'utf8').toString('base64');
+    }
+    if (typeof btoa !== 'undefined') {
+        // Modern Unicode-safe base64 encoding without deprecated unescape()
+        const bytes = new TextEncoder().encode(data);
+        const binaryString = Array.from(bytes, byte => String.fromCharCode(byte)).join('');
+        return btoa(binaryString);
+    }
+    throw new Error('No base64 encoding available');
+}
+/**
+ * Decode Base64 string
+ */
+function decodeBase64(data) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(data, 'base64').toString('utf8');
+    }
+    if (typeof atob !== 'undefined') {
+        // Modern Unicode-safe base64 decoding without deprecated escape()
+        const binaryString = atob(data);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+        return new TextDecoder('utf-8').decode(bytes);
+    }
+    throw new Error('No base64 decoding available');
+}
+/**
+ * Encode string to Base64URL (URL-safe)
+ */
+function encodeBase64URL(data) {
+    return encodeBase64(data)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=/g, '');
+}
+/**
+ * Decode Base64URL string
+ */
+function decodeBase64URL(data) {
+    let base64 = data.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4) {
+        base64 += '=';
+    }
+    return decodeBase64(base64);
+}
+/**
+ * Encode string to hexadecimal
+ */
+function encodeHex(data) {
+    return Array.from(data)
+        .map(char => char.charCodeAt(0).toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Decode hexadecimal string
+ */
+function decodeHex(data) {
+    if (data.length % 2 !== 0) {
+        throw new Error('Invalid hex string: length must be even');
+    }
+    if (!/^[0-9a-fA-F]*$/.test(data)) {
+        throw new Error('Invalid hex string: contains non-hex characters');
+    }
+    let result = '';
+    for (let i = 0; i < data.length; i += 2) {
+        result += String.fromCharCode(Number.parseInt(data.slice(i, i + 2), 16));
+    }
+    return result;
+}
+/**
+ * Encode string for URI
+ */
+function encodeURIString(data) {
+    return encodeURIComponent(data);
+}
+/**
+ * Decode URI-encoded string
+ */
+function decodeURIString(data) {
+    return decodeURIComponent(data);
+}
+/**
+ * Encode string as ASCII (validates ASCII-only)
+ */
+function encodeASCII(data) {
+    for (let i = 0; i < data.length; i++) {
+        const code = data.charCodeAt(i);
+        if (code > 127) {
+            throw new Error(`Non-ASCII character found at position ${i}: '${data[i]}' (code: ${code})`);
+        }
+    }
+    return data;
+}
+/**
+ * Decode ASCII string (no-op, validates printable ASCII)
+ */
+function decodeASCII(data) {
+    for (let i = 0; i < data.length; i++) {
+        const code = data.charCodeAt(i);
+        if (code < 32 || code > 126) {
+            throw new Error(`Non-printable ASCII character at position ${i}: code ${code}`);
+        }
+    }
+    return data;
+}
+/**
+ * Generic encode function
+ */
+function encode(data, format) {
+    switch (format) {
+        case 'base64':
+            return encodeBase64(data);
+        case 'base64url':
+            return encodeBase64URL(data);
+        case 'hex':
+            return encodeHex(data);
+        case 'uri':
+            return encodeURIString(data);
+        case 'ascii':
+            return encodeASCII(data);
+        default:
+            throw new Error(`Unsupported encoding format: ${format}`);
+    }
+}
+/**
+ * Generic decode function
+ */
+function decode(data, format) {
+    switch (format) {
+        case 'base64':
+            return decodeBase64(data);
+        case 'base64url':
+            return decodeBase64URL(data);
+        case 'hex':
+            return decodeHex(data);
+        case 'uri':
+            return decodeURIString(data);
+        case 'ascii':
+            return decodeASCII(data);
+        default:
+            throw new Error(`Unsupported decoding format: ${format}`);
+    }
+}
+/**
+ * Auto-detect encoding format
+ */
+function detectFormat(data) {
+    // Test patterns in order of specificity/confidence
+    if (/^[0-9a-fA-F]+$/.test(data) && data.length % 2 === 0) {
+        return 'hex';
+    }
+    // Base64url should be tested before base64 since it's more restrictive
+    if (/^[A-Za-z0-9\-_]*$/.test(data) && !data.includes('+') && !data.includes('/') && !data.includes('=') && data.length > 0) {
+        return 'base64url';
+    }
+    // Base64 with standard characters or padding
+    if (/^[A-Za-z0-9+/]*={0,2}$/.test(data) && data.length % 4 === 0 && (data.includes('+') || data.includes('/') || data.includes('='))) {
+        return 'base64';
+    }
+    if (data.includes('%') && /^[A-Za-z0-9\-_.~%!*'()]+$/.test(data)) {
+        return 'uri';
+    }
+    if (/^[\x20-\x7E]*$/.test(data)) {
+        return 'ascii';
+    }
+    throw new Error(`Cannot detect encoding format for: ${data.slice(0, 50)}...`);
+}
+/**
+ * Validate format of encoded data
+ */
+function validateFormat(data, format) {
+    try {
+        switch (format) {
+            case 'base64':
+                return /^[A-Za-z0-9+/]*={0,2}$/.test(data) && data.length % 4 === 0;
+            case 'base64url':
+                return /^[A-Za-z0-9\-_]*$/.test(data);
+            case 'hex':
+                return /^[0-9a-fA-F]*$/.test(data) && data.length % 2 === 0;
+            case 'uri':
+                decodeURIComponent(data);
+                return true;
+            case 'ascii':
+                return /^[\x20-\x7E]*$/.test(data);
+            default:
+                return false;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Chain multiple encodings
+ */
+function chain(data, formats) {
+    let result = data;
+    for (const format of formats) {
+        result = encode(result, format);
+    }
+    return result;
+}
+/**
+ * Reverse chain decodings
+ */
+function reverseChain(data, formats) {
+    let result = data;
+    for (const format of [...formats].reverse()) {
+        result = decode(result, format);
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @synet/encoder - Conscious Encoding/Decoding Unit
+ *
+ * Zero-dependency encoding operations following Unit Architecture doctrine.
+ *
+ * EXPORTS:
+ * - Encoder: Complete conscious encoder unit with teach/learn capabilities
+ * - Pure functions: Simple functional encoding operations
+ * - Result: Foundational error handling pattern
+ * - Types: All encoding-related interfaces
+ */
+export { Encoder } from './encoder.unit.js';
+export { Result } from './result.js';
+export type { EncoderConfig, EncoderProps, EncodingFormat, EncodingResult, DecodingResult, DetectionResult, ValidationResult } from './encoder.unit.js';
+export { encode, decode, encodeBase64, decodeBase64, encodeBase64URL, decodeBase64URL, encodeHex, decodeHex, encodeURIString, decodeURIString, encodeASCII, decodeASCII, detectFormat, validateFormat, chain, reverseChain, type EncodingFormat as FunctionEncodingFormat } from './functions.js';

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * @synet/encoder - Conscious Encoding/Decoding Unit
+ *
+ * Zero-dependency encoding operations following Unit Architecture doctrine.
+ *
+ * EXPORTS:
+ * - Encoder: Complete conscious encoder unit with teach/learn capabilities
+ * - Pure functions: Simple functional encoding operations
+ * - Result: Foundational error handling pattern
+ * - Types: All encoding-related interfaces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reverseChain = exports.chain = exports.validateFormat = exports.detectFormat = exports.decodeASCII = exports.encodeASCII = exports.decodeURIString = exports.encodeURIString = exports.decodeHex = exports.encodeHex = exports.decodeBase64URL = exports.encodeBase64URL = exports.decodeBase64 = exports.encodeBase64 = exports.decode = exports.encode = exports.Result = exports.Encoder = void 0;
+// Core Unit
+var encoder_unit_js_1 = require("./encoder.unit.js");
+Object.defineProperty(exports, "Encoder", { enumerable: true, get: function () { return encoder_unit_js_1.Encoder; } });
+// Result pattern (foundational)
+var result_js_1 = require("./result.js");
+Object.defineProperty(exports, "Result", { enumerable: true, get: function () { return result_js_1.Result; } });
+// Pure function exports for simple use cases
+var functions_js_1 = require("./functions.js");
+Object.defineProperty(exports, "encode", { enumerable: true, get: function () { return functions_js_1.encode; } });
+Object.defineProperty(exports, "decode", { enumerable: true, get: function () { return functions_js_1.decode; } });
+Object.defineProperty(exports, "encodeBase64", { enumerable: true, get: function () { return functions_js_1.encodeBase64; } });
+Object.defineProperty(exports, "decodeBase64", { enumerable: true, get: function () { return functions_js_1.decodeBase64; } });
+Object.defineProperty(exports, "encodeBase64URL", { enumerable: true, get: function () { return functions_js_1.encodeBase64URL; } });
+Object.defineProperty(exports, "decodeBase64URL", { enumerable: true, get: function () { return functions_js_1.decodeBase64URL; } });
+Object.defineProperty(exports, "encodeHex", { enumerable: true, get: function () { return functions_js_1.encodeHex; } });
+Object.defineProperty(exports, "decodeHex", { enumerable: true, get: function () { return functions_js_1.decodeHex; } });
+Object.defineProperty(exports, "encodeURIString", { enumerable: true, get: function () { return functions_js_1.encodeURIString; } });
+Object.defineProperty(exports, "decodeURIString", { enumerable: true, get: function () { return functions_js_1.decodeURIString; } });
+Object.defineProperty(exports, "encodeASCII", { enumerable: true, get: function () { return functions_js_1.encodeASCII; } });
+Object.defineProperty(exports, "decodeASCII", { enumerable: true, get: function () { return functions_js_1.decodeASCII; } });
+Object.defineProperty(exports, "detectFormat", { enumerable: true, get: function () { return functions_js_1.detectFormat; } });
+Object.defineProperty(exports, "validateFormat", { enumerable: true, get: function () { return functions_js_1.validateFormat; } });
+Object.defineProperty(exports, "chain", { enumerable: true, get: function () { return functions_js_1.chain; } });
+Object.defineProperty(exports, "reverseChain", { enumerable: true, get: function () { return functions_js_1.reverseChain; } });

package/dist/result.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Foundational Result Pattern for Encoder Operations
+ *
+ * Local copy following Unit Architecture Doctrine #14: ERROR BOUNDARY CLARITY
+ * Simple operations throw, complex operations use Result pattern
+ */
+export declare class Result<T> {
+    private readonly _value;
+    private readonly _error;
+    private readonly _errorCause?;
+    private constructor();
+    static success<T>(value: T): Result<T>;
+    static fail<T>(message: string, cause?: unknown): Result<T>;
+    get isSuccess(): boolean;
+    get isFailure(): boolean;
+    get value(): T;
+    get error(): string;
+    get errorCause(): unknown;
+    map<U>(fn: (value: T) => U): Result<U>;
+    flatMap<U>(fn: (value: T) => Result<U>): Result<U>;
+    getOrElse(defaultValue: T): T;
+    match<U>(onSuccess: (value: T) => U, onFailure: (error: string) => U): U;
+}

package/dist/result.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Foundational Result Pattern for Encoder Operations
+ *
+ * Local copy following Unit Architecture Doctrine #14: ERROR BOUNDARY CLARITY
+ * Simple operations throw, complex operations use Result pattern
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Result = void 0;
+class Result {
+    constructor(_value, _error, _errorCause) {
+        this._value = _value;
+        this._error = _error;
+        this._errorCause = _errorCause;
+    }
+    static success(value) {
+        return new Result(value, null);
+    }
+    static fail(message, cause) {
+        return new Result(null, message, cause);
+    }
+    get isSuccess() {
+        return this._error === null;
+    }
+    get isFailure() {
+        return this._error !== null;
+    }
+    get value() {
+        if (this._error !== null) {
+            throw new Error(`Attempted to get value from failed Result: ${this._error}`);
+        }
+        return this._value;
+    }
+    get error() {
+        return this._error || '';
+    }
+    get errorCause() {
+        return this._errorCause;
+    }
+    map(fn) {
+        if (this.isFailure) {
+            return Result.fail(this._error || 'Unknown error', this._errorCause);
+        }
+        try {
+            return Result.success(fn(this.value));
+        }
+        catch (error) {
+            return Result.fail(`Map operation failed: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    flatMap(fn) {
+        if (this.isFailure) {
+            return Result.fail(this._error || 'Unknown error', this._errorCause);
+        }
+        try {
+            return fn(this.value);
+        }
+        catch (error) {
+            return Result.fail(`FlatMap operation failed: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    getOrElse(defaultValue) {
+        return this.isSuccess ? this.value : defaultValue;
+    }
+    match(onSuccess, onFailure) {
+        return this.isSuccess ? onSuccess(this.value) : onFailure(this.error);
+    }
+}
+exports.Result = Result;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@synet/encoder",
+  "version": "1.0.0",
+  "description": "Unit Architecture compliant encoding/decoding operations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/synthetism/encoder.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev:test": "vitest",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "coverage": "vitest run --coverage",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --write ./src",
+    "format": "biome format --write './src'",
+    "prepublishOnly": "npm run lint:fix && npm run test && npm run build",
+    "version:dev": "npm version --no-git-tag-version prerelease --preid=dev",
+    "version:patch": "npm version --no-git-tag-version patch",
+    "version:minor": "npm version --no-git-tag-version minor",
+    "version:major": "npm version --no-git-tag-version major",
+    "publish:dev": "npm publish --registry=https://registry.dig.run/ --tag dev",
+    "publish:prod": "npm publish --registry=https://registry.npmjs.org/",
+    "release:dev": "npm run version:dev && npm run publish:dev",
+    "release:patch": "npm run version:patch && npm run publish:prod",
+    "release:minor": "npm run version:minor && npm run publish:prod",
+    "release:major": "npm run version:major && npm run publish:prod"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.15.31",
+    "@vitest/coverage-v8": "^3.1.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3"
+  },
+  "keywords": [
+    "Synet",
+    "Unit Architecture",
+    "Living beings in code"
+  ],
+  "author": "Synet Team",
+  "homepage": "https://synthetism.ai",
+  "license": "MIT",
+  "dependencies": {
+    "@synet/unit": "^1.0.6"
+  }
+}