@synet/encoder 1.0.0

package/README.md

@@ -0,0 +1,235 @@
+# @synet/encoder
+
+```bash
+8""""                                       8   8               
+8     eeeee eeee eeeee eeeee eeee eeeee     8   8 eeeee e eeeee 
+8eeee 8   8 8  8 8  88 8   8 8    8   8     8e  8 8   8 8   8   
+88    8e  8 8e   8   8 8e  8 8eee 8eee8e    88  8 8e  8 8e  8e  
+88    88  8 88   8   8 88  8 88   88   8    88  8 88  8 88  88  
+88eee 88  8 88e8 8eee8 88ee8 88ee 88   8    88ee8 88  8 88  88  
+                                                                
+version:1.0.0                                                                
+```
+**Production-ready Unit Architecture compliant encoding/decoding operations**
+
+A conscious software unit that transforms data between multiple encoding formats with immutable design and comprehensive validation.
+
+## Features
+
+- **Unit Architecture Compliant** - Consciousness-based design with teaching/learning capabilities
+- **Immutable by Design** - No mutable state, purely functional operations
+- **Multiple Formats** - Base64, Base64URL, Hex, URI, ASCII encoding support
+- **Auto-detection** - Intelligent format detection with confidence scoring
+- **Pure Functions** - Serverless-ready stateless operations
+- **Chainable Operations** - Sequential encoding/decoding workflows
+- **Zero Dependencies** - Only Node.js/browser native APIs
+- **Result Pattern** - Error-safe operations with validation
+- **Teaching Capability** - Other units can learn encoding capabilities
+
+## Installation
+
+```bash
+npm install @synet/encoder
+```
+
+## Quick Start
+
+### Unit Architecture Pattern
+
+```typescript
+import { Encoder } from '@synet/encoder';
+
+// Create encoder unit
+const encoder = Encoder.create({
+  defaultFormat: 'base64',
+  autoDetect: true,
+  strictMode: false
+});
+
+// Encode data (Result pattern for safety)
+const encoded = encoder.encode('Hello World', 'base64');
+if (encoded.isSuccess) {
+  console.log(encoded.value.encoded); // SGVsbG8gV29ybGQ=
+}
+
+// Auto-detection decoding
+const decoded = encoder.decode('48656c6c6f'); // Auto-detects hex
+if (decoded.isSuccess) {
+  console.log(decoded.value.decoded); // Hello
+  console.log(decoded.value.detectedFormat); // hex
+}
+
+// Format detection
+const detection = encoder.detect('SGVsbG8gV29ybGQh');
+console.log(detection.format); // base64url
+console.log(detection.confidence); // 0.9
+```
+
+### Pure Functions Pattern
+
+```typescript
+import { 
+  encode, 
+  decode, 
+  base64Encode, 
+  hexDecode,
+  detectFormat,
+  chainEncode 
+} from '@synet/encoder';
+
+// Simple encoding
+const encoded = encode('Hello World', 'base64');
+console.log(encoded); // SGVsbG8gV29ybGQ=
+
+// Format-specific functions
+const hex = hexEncode('Hello');
+console.log(hex); // 48656c6c6f
+
+// Auto-detection
+const format = detectFormat('48656c6c6f');
+console.log(format); // hex
+
+// Chain operations
+const chained = chainEncode('Hello', ['hex', 'base64']);
+console.log(chained); // NDg2NTZjNmM2Zg==
+```
+
+## Supported Formats
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `base64` | Standard Base64 (RFC 4648) | `SGVsbG8gV29ybGQ=` |
+| `base64url` | URL-safe Base64 (no padding) | `SGVsbG8gV29ybGQh` |
+| `hex` | Hexadecimal encoding | `48656c6c6f` |
+| `uri` | URI component encoding | `Hello%20World` |
+| `ascii` | ASCII text validation | `Hello World` |
+
+## Configuration Options
+
+```typescript
+const encoder = Encoder.create({
+  defaultFormat: 'base64',    // Default encoding format
+  autoDetect: true,           // Enable auto-detection for decoding
+  strictMode: false,          // Strict validation mode
+  maxInputSize: 10 * 1024 * 1024, // 10MB input limit
+  validateOutput: true        // Validate encoded output
+});
+```
+
+## Unit Architecture Integration
+
+### Teaching Capabilities
+
+```typescript
+const encoder = Encoder.create();
+
+// Teach encoding capabilities to other units
+const learner = SomeOtherUnit.create();
+learner.learn([encoder.teach()]);
+
+// Use learned capabilities
+const result = learner.execute('encoder.encode', 'Hello', 'base64');
+```
+
+### Learning from Others
+
+```typescript
+// Encoder can learn from crypto units for advanced operations
+const cryptoUnit = CryptoUnit.create();
+encoder.learn([cryptoUnit.teach()]);
+
+// Now has enhanced capabilities
+encoder.execute('crypto.sign', data);
+```
+
+## Error Handling
+
+The encoder follows **Doctrine #14: ERROR BOUNDARY CLARITY**:
+
+- **Simple operations** (detect, validate) throw exceptions
+- **Complex operations** (encode, decode, chain) return Result objects
+
+```typescript
+// Throws on error (simple classification)
+try {
+  const detection = encoder.detect('invalid-data');
+} catch (error) {
+  console.log('Detection failed:', error.message);
+}
+
+// Result pattern (complex validation)
+const encoded = encoder.encode('data', 'base64');
+if (encoded.isFailure) {
+  console.log('Encoding failed:', encoded.error);
+  console.log('Cause:', encoded.errorCause);
+}
+```
+
+## Chain Operations
+
+```typescript
+// Sequential encoding
+const result = encoder.chain('Hello', ['hex', 'base64', 'uri']);
+if (result.isSuccess) {
+  console.log(result.value.encoded);
+  console.log(result.value.compressionRatio);
+}
+
+// Reverse decoding
+const reversed = encoder.reverse(result.value.encoded, ['hex', 'base64', 'uri']);
+console.log(reversed.value.decoded); // Hello
+```
+
+## Performance Features
+
+- **Stateless operations** - No side effects, safe for concurrency
+- **Immutable design** - Thread-safe by default
+- **Pure functions** - Optimal for serverless environments
+- **Zero allocations** - Efficient for high-throughput scenarios
+
+## Browser Compatibility
+
+Works in both Node.js and browser environments:
+
+```typescript
+// Automatically uses Buffer in Node.js, btoa/atob in browsers
+const encoder = Encoder.create();
+const encoded = encoder.encode('Hello World', 'base64');
+```
+
+## Help System
+
+```typescript
+// Get unit help
+encoder.help();
+
+// Static help
+Encoder.help();
+
+// Capability inspection
+console.log(encoder.capabilities());
+console.log(encoder.whoami());
+```
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type { 
+  EncodingFormat, 
+  EncodingResult, 
+  DecodingResult,
+  DetectionResult 
+} from '@synet/encoder';
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Part of the [Unit Architecture](https://github.com/synthetism/unit) ecosystem. See the main repository for contribution guidelines.
+
+---

package/biome.json

@@ -0,0 +1,37 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+		"files": {
+		"ignoreUnknown": false,
+		"ignore": ["src/services/vault-manager.ts","docs/**", "dist/**", "node_modules/**", "coverage/**", "test/**", "tests/**", "examples/**", "scripts/**"]	
+	},
+	"formatter": {
+		"enabled": true,
+		"indentWidth": 2,
+		"lineWidth": 80,
+		"indentStyle": "space"
+	},
+	"organizeImports": {
+		"enabled": true
+	},
+
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"complexity": {
+      			  "noStaticOnlyClass": "off"
+     		 }
+		}	
+	},
+	
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	}
+}

package/dist/encoder.unit.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+import { Unit, type UnitProps, type TeachingContract } from '@synet/unit';
+import { Result } from './result.js';
+/**
+ * External input configuration for static create()
+ */
+export interface EncoderConfig {
+    defaultFormat?: EncodingFormat;
+    strictMode?: boolean;
+    autoDetect?: boolean;
+    maxInputSize?: number;
+    validateOutput?: boolean;
+}
+/**
+ * Internal state after validation (implements UnitProps)
+ */
+export interface EncoderProps extends UnitProps {
+    defaultFormat: EncodingFormat;
+    strictMode: boolean;
+    autoDetect: boolean;
+    maxInputSize: number;
+    validateOutput: boolean;
+    readonly created: Date;
+}
+/**
+ * Encoding format types
+ */
+export type EncodingFormat = 'base64' | 'base64url' | 'hex' | 'uri' | 'ascii';
+/**
+ * Encoding operation result
+ */
+export interface EncodingResult {
+    readonly encoded: string;
+    readonly originalSize: number;
+    readonly encodedSize: number;
+    readonly format: EncodingFormat;
+    readonly compressionRatio: number;
+    readonly timestamp: Date;
+}
+/**
+ * Decoding operation result
+ */
+export interface DecodingResult {
+    readonly decoded: string;
+    readonly detectedFormat: EncodingFormat;
+    readonly isValid: boolean;
+    readonly originalSize: number;
+    readonly timestamp: Date;
+}
+/**
+ * Format detection result
+ */
+export interface DetectionResult {
+    readonly format: EncodingFormat;
+    readonly confidence: number;
+    readonly reasons: string[];
+    readonly timestamp: Date;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    readonly isValid: boolean;
+    readonly format: EncodingFormat;
+    readonly errors: string[];
+    readonly suggestions: string[];
+}
+/**
+ * Encoder Implementation
+ *
+ * Doctrine #1: ZERO DEPENDENCY (only Node.js/browser native APIs)
+ * Doctrine #17: VALUE OBJECT FOUNDATION (immutable with identity and capabilities)
+ */
+export declare class Encoder extends Unit<EncoderProps> {
+    protected constructor(props: EncoderProps);
+    static create(config?: EncoderConfig): Encoder;
+    help(): void;
+    teach(): TeachingContract;
+    /**
+     * Encode data to specified format (Result - complex validation operation)
+     */
+    encode(data: string, format?: EncodingFormat): Result<EncodingResult>;
+    /**
+     * Decode data with optional format hint (Result - complex auto-detection operation)
+     */
+    decode(data: string, format?: EncodingFormat): Result<DecodingResult>;
+    /**
+     * Chain multiple encoding operations (Result - complex multi-step operation)
+     */
+    chain(data: string, formats: EncodingFormat[]): Result<EncodingResult>;
+    /**
+     * Reverse chain decoding (Result - complex multi-step operation)
+     */
+    reverse(data: string, formats: EncodingFormat[]): Result<DecodingResult>;
+    /**
+     * Auto-detect encoding format (throw on error - simple classification operation)
+     */
+    detect(data: string): DetectionResult;
+    /**
+     * Validate encoded data format (throw on error - simple validation operation)
+     */
+    validate(data: string, format: EncodingFormat): ValidationResult;
+    private performEncode;
+    private performDecode;
+    private encodeBase64;
+    private decodeBase64;
+    private encodeBase64URL;
+    private decodeBase64URL;
+    private encodeHex;
+    private decodeHex;
+    private encodeURI;
+    private decodeURI;
+    private encodeASCII;
+    private decodeASCII;
+    private isValidInput;
+    whoami(): string;
+    toJSON(): Record<string, unknown>;
+}