@synet/encoder 1.0.0

package/src/functions.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 function encodeBase64(data: string): string {
+  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
+ */
+export function decodeBase64(data: string): string {
+  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)
+ */
+export function encodeBase64URL(data: string): string {
+  return encodeBase64(data)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+}
+
+/**
+ * Decode Base64URL string
+ */
+export function decodeBase64URL(data: string): string {
+  let base64 = data.replace(/-/g, '+').replace(/_/g, '/');
+  while (base64.length % 4) {
+    base64 += '=';
+  }
+  return decodeBase64(base64);
+}
+
+/**
+ * Encode string to hexadecimal
+ */
+export function encodeHex(data: string): string {
+  return Array.from(data)
+    .map(char => char.charCodeAt(0).toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Decode hexadecimal string
+ */
+export function decodeHex(data: string): string {
+  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
+ */
+export function encodeURIString(data: string): string {
+  return encodeURIComponent(data);
+}
+
+/**
+ * Decode URI-encoded string
+ */
+export function decodeURIString(data: string): string {
+  return decodeURIComponent(data);
+}
+
+/**
+ * Encode string as ASCII (validates ASCII-only)
+ */
+export function encodeASCII(data: string): string {
+  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)
+ */
+export function decodeASCII(data: string): string {
+  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
+ */
+export function encode(data: string, format: EncodingFormat): string {
+  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
+ */
+export function decode(data: string, format: EncodingFormat): string {
+  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
+ */
+export function detectFormat(data: string): EncodingFormat {
+  // 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
+ */
+export function validateFormat(data: string, format: EncodingFormat): boolean {
+  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
+ */
+export function chain(data: string, formats: EncodingFormat[]): string {
+  let result = data;
+  for (const format of formats) {
+    result = encode(result, format);
+  }
+  return result;
+}
+
+/**
+ * Reverse chain decodings
+ */
+export function reverseChain(data: string, formats: EncodingFormat[]): string {
+  let result = data;
+  for (const format of [...formats].reverse()) {
+    result = decode(result, format);
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @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
+ */
+
+// Core Unit
+export { Encoder } from './encoder.unit.js';
+
+// Result pattern (foundational)
+export { Result } from './result.js';
+
+// Types
+export type {
+  EncoderConfig,
+  EncoderProps,
+  EncodingFormat,
+  EncodingResult,
+  DecodingResult,
+  DetectionResult,
+  ValidationResult
+} from './encoder.unit.js';
+
+// Pure function exports for simple use cases
+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/src/result.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 class Result<T> {
+  private constructor(
+    private readonly _value: T | null,
+    private readonly _error: string | null,
+    private readonly _errorCause?: unknown
+  ) {}
+
+  static success<T>(value: T): Result<T> {
+    return new Result(value, null);
+  }
+
+  static fail<T>(message: string, cause?: unknown): Result<T> {
+    return new Result<T>(null, message, cause);
+  }
+
+  get isSuccess(): boolean {
+    return this._error === null;
+  }
+
+  get isFailure(): boolean {
+    return this._error !== null;
+  }
+
+  get value(): T {
+    if (this._error !== null) {
+      throw new Error(`Attempted to get value from failed Result: ${this._error}`);
+    }
+    return this._value as T;
+  }
+
+  get error(): string {
+    return this._error || '';
+  }
+
+  get errorCause(): unknown {
+    return this._errorCause;
+  }
+
+  map<U>(fn: (value: T) => U): Result<U> {
+    if (this.isFailure) {
+      return Result.fail<U>(this._error || 'Unknown error', this._errorCause);
+    }
+    try {
+      return Result.success(fn(this.value));
+    } catch (error) {
+      return Result.fail<U>(
+        `Map operation failed: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+
+  flatMap<U>(fn: (value: T) => Result<U>): Result<U> {
+    if (this.isFailure) {
+      return Result.fail<U>(this._error || 'Unknown error', this._errorCause);
+    }
+    try {
+      return fn(this.value);
+    } catch (error) {
+      return Result.fail<U>(
+        `FlatMap operation failed: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+
+  getOrElse(defaultValue: T): T {
+    return this.isSuccess ? this.value : defaultValue;
+  }
+
+  match<U>(onSuccess: (value: T) => U, onFailure: (error: string) => U): U {
+    return this.isSuccess ? onSuccess(this.value) : onFailure(this.error);
+  }
+}