@synet/encoder 1.0.0

package/dist/encoder.unit.js

@@ -0,0 +1,517 @@
+"use strict";
+/**
+ * Encoder Unit - Conscious Encoding/Decoding Operations
+ *
+ * SYNET Unit Architecture v1.0.6 Implementation
+ *
+ * Philosophy: One unit, one goal - reliable data transformation
+ *
+ * Native Capabilities:
+ * - encode() - Transform data to specified format
+ * - decode() - Reverse transformation with validation
+ * - detect() - Auto-detect encoding format
+ * - validate() - Verify encoded data integrity
+ * - chain() - Sequential encoding operations
+ *
+ * Supported Formats: Base64, Base64URL, Hex, URI, ASCII
+ *
+ * @author SYNET ALPHA
+ * @version 1.0.0
+ * @follows Unit Architecture Doctrine v1.0.6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Encoder = void 0;
+const unit_1 = require("@synet/unit");
+const result_js_1 = require("./result.js");
+/**
+ * Encoder Implementation
+ *
+ * Doctrine #1: ZERO DEPENDENCY (only Node.js/browser native APIs)
+ * Doctrine #17: VALUE OBJECT FOUNDATION (immutable with identity and capabilities)
+ */
+class Encoder extends unit_1.Unit {
+    // Doctrine #4: CREATE NOT CONSTRUCT (protected constructor)
+    constructor(props) {
+        super(props);
+    }
+    // Doctrine #4: CREATE NOT CONSTRUCT (static create with validation)
+    static create(config = {}) {
+        // Doctrine #3: PROPS CONTAIN EVERYTHING (validate and transform config to props)
+        const props = {
+            // Doctrine #7: EVERY UNIT MUST HAVE DNA
+            dna: (0, unit_1.createUnitSchema)({
+                id: 'encoder',
+                version: '1.0.0'
+            }),
+            defaultFormat: config.defaultFormat || 'base64',
+            strictMode: config.strictMode ?? false,
+            autoDetect: config.autoDetect ?? true,
+            maxInputSize: config.maxInputSize || 10 * 1024 * 1024, // 10MB default
+            validateOutput: config.validateOutput ?? true,
+            created: new Date()
+        };
+        return new Encoder(props);
+    }
+    // Doctrine #11: ALWAYS HELP (living documentation)
+    help() {
+        console.log(`
+
+
+Hi, I am Encoder Unit [${this.dna.id}] v${this.dna.version} - Data Transformation Service
+
+IDENTITY: ${this.whoami()}
+DEFAULT FORMAT: ${this.props.defaultFormat}
+STRICT MODE: ${this.props.strictMode}
+AUTO DETECT: ${this.props.autoDetect}
+MAX INPUT: ${(this.props.maxInputSize / 1024 / 1024).toFixed(1)}MB
+STATUS: IMMUTABLE (stateless operations)
+
+NATIVE CAPABILITIES:
+• encode(data, format?) - Transform data to specified format (Result for validation)
+• decode(data, format?) - Reverse transformation with auto-detection (Result)
+• detect(data) - Auto-detect encoding format with confidence (throws on error)
+• validate(data, format) - Verify encoded data integrity (throws on error)
+• chain(data, formats) - Sequential encoding operations (Result)
+• reverse(data, formats) - Reverse sequential decoding (Result)
+
+SUPPORTED FORMATS:
+• base64: Standard Base64 encoding (RFC 4648)
+• base64url: URL-safe Base64 encoding
+• hex: Hexadecimal encoding (lowercase)
+• uri: URI component encoding
+• ascii: ASCII text encoding
+
+USAGE EXAMPLES:
+  const encoder = Encoder.create();
+  
+  // Simple operations (Result pattern for validation)
+  const encoded = encoder.encode('Hello World', 'base64');
+  if (encoded.isSuccess) {
+    console.log(encoded.value.encoded); // SGVsbG8gV29ybGQ=
+  }
+  
+  // Auto-detection decoding
+  const decoded = encoder.decode('SGVsbG8gV29ybGQ=');
+  if (decoded.isSuccess) {
+    console.log(decoded.value.decoded); // Hello World
+  }
+  
+  // Format detection
+  const format = encoder.detect('48656c6c6f'); // hex
+  console.log(format.format); // 'hex'
+
+LEARNING CAPABILITIES:
+Other units can learn from me:
+  unit.learn([encoder.teach()]);
+  unit.execute('encoder.encode', data, format);
+
+I TEACH:
+• encode(data, format) - Encoding capability
+• decode(data, format) - Decoding capability  
+• detect(data) - Format detection capability
+• validate(data, format) - Validation capability
+• chain(data, formats) - Sequential encoding capability
+
+`);
+    }
+    // Doctrine #2: TEACH/LEARN PARADIGM (every unit must teach)
+    // Doctrine #9: ALWAYS TEACH (explicit capability binding)
+    // Doctrine #19: CAPABILITY LEAKAGE PREVENTION (teach only native capabilities)
+    teach() {
+        return {
+            // Doctrine #12: NAMESPACE EVERYTHING (unitId for namespacing)
+            unitId: this.dna.id,
+            capabilities: {
+                // Native encoding capabilities only - wrapped for unknown[] compatibility
+                encode: ((...args) => this.encode(args[0], args[1])),
+                decode: ((...args) => this.decode(args[0], args[1])),
+                detect: ((...args) => this.detect(args[0])),
+                validate: ((...args) => this.validate(args[0], args[1])),
+                chain: ((...args) => this.chain(args[0], args[1])),
+                // Metadata access
+                getDefaultFormat: (() => this.props.defaultFormat),
+                isStrictMode: (() => this.props.strictMode),
+                getMaxInputSize: (() => this.props.maxInputSize)
+            }
+        };
+    }
+    // Doctrine #14: ERROR BOUNDARY CLARITY (Result for complex operations)
+    /**
+     * Encode data to specified format (Result - complex validation operation)
+     */
+    encode(data, format) {
+        try {
+            const encodingFormat = format || this.props.defaultFormat;
+            // Input validation
+            if (data.length > this.props.maxInputSize) {
+                return result_js_1.Result.fail(`Input too large: ${data.length} bytes (max: ${this.props.maxInputSize})`);
+            }
+            if (this.props.strictMode && !this.isValidInput(data)) {
+                return result_js_1.Result.fail('Invalid input for strict mode');
+            }
+            const encoded = this.performEncode(data, encodingFormat);
+            // Output validation if enabled
+            if (this.props.validateOutput) {
+                const validation = this.validate(encoded, encodingFormat);
+                if (!validation.isValid) {
+                    return result_js_1.Result.fail(`Output validation failed: ${validation.errors.join(', ')}`);
+                }
+            }
+            const result = {
+                encoded,
+                originalSize: data.length,
+                encodedSize: encoded.length,
+                format: encodingFormat,
+                compressionRatio: encoded.length / data.length,
+                timestamp: new Date()
+            };
+            return result_js_1.Result.success(result);
+        }
+        catch (error) {
+            return result_js_1.Result.fail(`Encoding failed: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    /**
+     * Decode data with optional format hint (Result - complex auto-detection operation)
+     */
+    decode(data, format) {
+        try {
+            // Auto-detect format if not provided and auto-detection is enabled
+            let detectedFormat;
+            if (format) {
+                detectedFormat = format;
+            }
+            else if (this.props.autoDetect) {
+                detectedFormat = this.detect(data).format;
+            }
+            else {
+                detectedFormat = this.props.defaultFormat;
+            }
+            // Input validation
+            const validation = this.validate(data, detectedFormat);
+            if (!validation.isValid) {
+                if (this.props.strictMode) {
+                    return result_js_1.Result.fail(`Invalid ${detectedFormat} format: ${validation.errors.join(', ')}`);
+                }
+                // In non-strict mode, still fail if the format is completely wrong
+                if (validation.errors.some(err => err.includes('invalid') || err.includes('Invalid'))) {
+                    return result_js_1.Result.fail(`Invalid ${detectedFormat} format: ${validation.errors.join(', ')}`, new Error(`Validation failed for ${detectedFormat}`));
+                }
+            }
+            const decoded = this.performDecode(data, detectedFormat);
+            const result = {
+                decoded,
+                detectedFormat,
+                isValid: validation.isValid,
+                originalSize: data.length,
+                timestamp: new Date()
+            };
+            return result_js_1.Result.success(result);
+        }
+        catch (error) {
+            return result_js_1.Result.fail(`Decoding failed: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    /**
+     * Chain multiple encoding operations (Result - complex multi-step operation)
+     */
+    chain(data, formats) {
+        try {
+            let result = data;
+            let totalRatio = 1;
+            for (const format of formats) {
+                const encoded = this.encode(result, format);
+                if (encoded.isFailure) {
+                    return result_js_1.Result.fail(`Chain failed at ${format}: ${encoded.error}`);
+                }
+                result = encoded.value.encoded;
+                totalRatio *= encoded.value.compressionRatio;
+            }
+            const chainResult = {
+                encoded: result,
+                originalSize: data.length,
+                encodedSize: result.length,
+                format: formats[formats.length - 1], // Final format
+                compressionRatio: totalRatio,
+                timestamp: new Date()
+            };
+            return result_js_1.Result.success(chainResult);
+        }
+        catch (error) {
+            return result_js_1.Result.fail(`Chain encoding failed: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    /**
+     * Reverse chain decoding (Result - complex multi-step operation)
+     */
+    reverse(data, formats) {
+        try {
+            let result = data;
+            const reversedFormats = [...formats].reverse();
+            for (const format of reversedFormats) {
+                const decoded = this.decode(result, format);
+                if (decoded.isFailure) {
+                    return result_js_1.Result.fail(`Reverse chain failed at ${format}: ${decoded.error}`);
+                }
+                result = decoded.value.decoded;
+            }
+            const reverseResult = {
+                decoded: result,
+                detectedFormat: formats[0], // Original format
+                isValid: true,
+                originalSize: data.length,
+                timestamp: new Date()
+            };
+            return result_js_1.Result.success(reverseResult);
+        }
+        catch (error) {
+            return result_js_1.Result.fail(`Reverse chain failed: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    // Doctrine #14: ERROR BOUNDARY CLARITY (throws for simple operations)
+    /**
+     * Auto-detect encoding format (throw on error - simple classification operation)
+     */
+    detect(data) {
+        const patterns = [
+            {
+                format: 'hex',
+                test: (s) => /^[0-9a-fA-F]+$/.test(s) && s.length % 2 === 0,
+                confidence: 0.95,
+                reason: 'Matches hexadecimal pattern with even length'
+            },
+            {
+                format: 'base64url',
+                test: (s) => /^[A-Za-z0-9\-_]*$/.test(s) && !s.includes('+') && !s.includes('/') && !s.includes('=') && s.length > 0,
+                confidence: 0.9,
+                reason: 'Matches base64url character set (URL-safe, no padding)'
+            },
+            {
+                format: 'base64',
+                test: (s) => /^[A-Za-z0-9+/]*={0,2}$/.test(s) && s.length % 4 === 0 && (s.includes('+') || s.includes('/') || s.includes('=')),
+                confidence: 0.85,
+                reason: 'Matches base64 character set with standard chars or padding'
+            },
+            {
+                format: 'uri',
+                test: (s) => s.includes('%') && /^[A-Za-z0-9\-_.~%!*'()]+$/.test(s),
+                confidence: 0.8,
+                reason: 'Contains URI percent-encoding characters'
+            },
+            {
+                format: 'ascii',
+                test: (s) => /^[\x20-\x7E]*$/.test(s),
+                confidence: 0.7,
+                reason: 'Contains only printable ASCII characters'
+            }
+        ];
+        const matches = patterns.filter(p => p.test(data));
+        if (matches.length === 0) {
+            throw new Error(`Cannot detect encoding format for data: ${data.slice(0, 50)}...`);
+        }
+        // Return highest confidence match
+        const bestMatch = matches.reduce((best, current) => current.confidence > best.confidence ? current : best);
+        return {
+            format: bestMatch.format,
+            confidence: bestMatch.confidence,
+            reasons: matches.map(m => m.reason),
+            timestamp: new Date()
+        };
+    }
+    /**
+     * Validate encoded data format (throw on error - simple validation operation)
+     */
+    validate(data, format) {
+        const errors = [];
+        const suggestions = [];
+        try {
+            switch (format) {
+                case 'base64':
+                    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+                        errors.push('Contains invalid base64 characters');
+                        suggestions.push('Remove invalid characters or try base64url format');
+                    }
+                    if (data.length % 4 !== 0) {
+                        errors.push('Invalid base64 length (must be multiple of 4)');
+                        suggestions.push('Add padding with = characters');
+                    }
+                    break;
+                case 'base64url':
+                    if (!/^[A-Za-z0-9\-_]*$/.test(data)) {
+                        errors.push('Contains invalid base64url characters');
+                        suggestions.push('Use only A-Z, a-z, 0-9, -, _ characters');
+                    }
+                    break;
+                case 'hex':
+                    if (!/^[0-9a-fA-F]*$/.test(data)) {
+                        errors.push('Contains invalid hexadecimal characters');
+                        suggestions.push('Use only 0-9, a-f, A-F characters');
+                    }
+                    if (data.length % 2 !== 0) {
+                        errors.push('Invalid hex length (must be even)');
+                        suggestions.push('Add leading zero or remove extra character');
+                    }
+                    break;
+                case 'uri':
+                    try {
+                        decodeURIComponent(data);
+                    }
+                    catch {
+                        errors.push('Invalid URI encoding');
+                        suggestions.push('Check percent-encoding format');
+                    }
+                    break;
+                case 'ascii':
+                    if (!/^[\x20-\x7E]*$/.test(data)) {
+                        errors.push('Contains non-ASCII characters');
+                        suggestions.push('Use only printable ASCII characters (32-126)');
+                    }
+                    break;
+                default:
+                    throw new Error(`Unknown format: ${format}`);
+            }
+            return {
+                isValid: errors.length === 0,
+                format,
+                errors,
+                suggestions
+            };
+        }
+        catch (error) {
+            throw new Error(`Validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Doctrine #8: PURE FUNCTION HEARTS (core logic as pure functions)
+    performEncode(data, format) {
+        switch (format) {
+            case 'base64':
+                return this.encodeBase64(data);
+            case 'base64url':
+                return this.encodeBase64URL(data);
+            case 'hex':
+                return this.encodeHex(data);
+            case 'uri':
+                return this.encodeURI(data);
+            case 'ascii':
+                return this.encodeASCII(data);
+            default:
+                throw new Error(`Unsupported encoding format: ${format}`);
+        }
+    }
+    performDecode(data, format) {
+        switch (format) {
+            case 'base64':
+                return this.decodeBase64(data);
+            case 'base64url':
+                return this.decodeBase64URL(data);
+            case 'hex':
+                return this.decodeHex(data);
+            case 'uri':
+                return this.decodeURI(data);
+            case 'ascii':
+                return this.decodeASCII(data);
+            default:
+                throw new Error(`Unsupported decoding format: ${format}`);
+        }
+    }
+    // Base64 implementation (cross-platform Node.js/Browser)
+    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');
+    }
+    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');
+    }
+    // Base64URL implementation
+    encodeBase64URL(data) {
+        return this.encodeBase64(data)
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=/g, '');
+    }
+    decodeBase64URL(data) {
+        let base64 = data.replace(/-/g, '+').replace(/_/g, '/');
+        while (base64.length % 4) {
+            base64 += '=';
+        }
+        return this.decodeBase64(base64);
+    }
+    // Hex implementation
+    encodeHex(data) {
+        return Array.from(data)
+            .map(char => char.charCodeAt(0).toString(16).padStart(2, '0'))
+            .join('');
+    }
+    decodeHex(data) {
+        const hex = data.replace(/[^0-9a-fA-F]/g, '');
+        let result = '';
+        for (let i = 0; i < hex.length; i += 2) {
+            result += String.fromCharCode(Number.parseInt(hex.slice(i, i + 2), 16));
+        }
+        return result;
+    }
+    // URI implementation
+    encodeURI(data) {
+        return encodeURIComponent(data);
+    }
+    decodeURI(data) {
+        return decodeURIComponent(data);
+    }
+    // ASCII implementation
+    encodeASCII(data) {
+        return Array.from(data)
+            .map(char => {
+            const code = char.charCodeAt(0);
+            if (code > 127) {
+                throw new Error(`Non-ASCII character found: ${char} (code: ${code})`);
+            }
+            return char;
+        })
+            .join('');
+    }
+    decodeASCII(data) {
+        return data; // ASCII is already decoded
+    }
+    // Utility methods
+    isValidInput(data) {
+        // Basic input validation for strict mode
+        return typeof data === 'string' && data.length > 0;
+    }
+    // Standard unit identification
+    whoami() {
+        return `EncoderUnit[${this.dna.id}@${this.dna.version}]`;
+    }
+    // JSON serialization (no sensitive data exposed)
+    toJSON() {
+        return {
+            type: 'EncoderUnit',
+            dna: this.dna,
+            defaultFormat: this.props.defaultFormat,
+            strictMode: this.props.strictMode,
+            autoDetect: this.props.autoDetect,
+            learnedCapabilities: this.capabilities(), // This calls the base Unit class method
+            created: this.props.created
+        };
+    }
+}
+exports.Encoder = Encoder;

package/dist/functions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure Encoding Functions - Serverless Ready
+ *
+ * Simple, stateless functions for encoding/decoding operations.
+ * These throw on error (simple operations) following Doctrine #14.
+ */
+/**
+ * Encoding format types
+ */
+export type EncodingFormat = 'base64' | 'base64url' | 'hex' | 'uri' | 'ascii';
+/**
+ * Encode string to Base64
+ */
+export declare function encodeBase64(data: string): string;
+/**
+ * Decode Base64 string
+ */
+export declare function decodeBase64(data: string): string;
+/**
+ * Encode string to Base64URL (URL-safe)
+ */
+export declare function encodeBase64URL(data: string): string;
+/**
+ * Decode Base64URL string
+ */
+export declare function decodeBase64URL(data: string): string;
+/**
+ * Encode string to hexadecimal
+ */
+export declare function encodeHex(data: string): string;
+/**
+ * Decode hexadecimal string
+ */
+export declare function decodeHex(data: string): string;
+/**
+ * Encode string for URI
+ */
+export declare function encodeURIString(data: string): string;
+/**
+ * Decode URI-encoded string
+ */
+export declare function decodeURIString(data: string): string;
+/**
+ * Encode string as ASCII (validates ASCII-only)
+ */
+export declare function encodeASCII(data: string): string;
+/**
+ * Decode ASCII string (no-op, validates printable ASCII)
+ */
+export declare function decodeASCII(data: string): string;
+/**
+ * Generic encode function
+ */
+export declare function encode(data: string, format: EncodingFormat): string;
+/**
+ * Generic decode function
+ */
+export declare function decode(data: string, format: EncodingFormat): string;
+/**
+ * Auto-detect encoding format
+ */
+export declare function detectFormat(data: string): EncodingFormat;
+/**
+ * Validate format of encoded data
+ */
+export declare function validateFormat(data: string, format: EncodingFormat): boolean;
+/**
+ * Chain multiple encodings
+ */
+export declare function chain(data: string, formats: EncodingFormat[]): string;
+/**
+ * Reverse chain decodings
+ */
+export declare function reverseChain(data: string, formats: EncodingFormat[]): string;