@mks2508/hyperdiff-utils 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Error handling for the Hyperdiff engine.
+ *
+ * Maps FFI error codes (u16 from errors.zig ErrorCode enum)
+ * to structured ResultError<HyperdiffErrorCode> from @mks2508/no-throw.
+ *
+ * Every error code, message, and domain is 1:1 with errors.zig.
+ */
+import type { ResultError } from '@mks2508/no-throw';
+/** All valid Hyperdiff error code string literals. */
+export type HyperdiffErrorCode = 'FILE_NOT_FOUND' | 'PERMISSION_DENIED' | 'FILE_READ_ERROR' | 'FILE_WRITE_ERROR' | 'MMAP_FAILED' | 'MMAP_UNMAP_FAILED' | 'FILE_TOO_LARGE' | 'INVALID_PATH' | 'INVALID_UTF8' | 'INVALID_ENCODING' | 'EMPTY_INPUT' | 'HASH_MISMATCH' | 'INVALID_HASH_SIZE' | 'HASH_COLLISION_DETECTED' | 'INVALID_CACHE' | 'CACHE_CORRUPTED' | 'CACHE_VERSION_MISMATCH' | 'CACHE_CHECKSUM_FAILED' | 'CACHE_EXPIRED' | 'CACHE_INCOMPLETE' | 'THREAD_SPAWN_FAILED' | 'THREAD_POOL_EXHAUSTED' | 'THREAD_JOIN_FAILED' | 'THREAD_CANCELLED' | 'THREAD_INVALID_STATE' | 'THREAD_RESOURCE_LIMIT' | 'INVALID_ALGORITHM' | 'ALGORITHM_NOT_SUPPORTED' | 'INTERNAL_ERROR' | 'STACK_OVERFLOW' | 'RECURSION_LIMIT_EXCEEDED' | 'MIDDLE_SNAKE_NOT_FOUND' | 'LCS_NOT_FOUND' | 'EDIT_SCRIPT_INVALID' | 'DIFF_TIMEOUT' | 'DIFF_CANCELLED' | 'INVALID_INPUT' | 'LINE_COUNT_MISMATCH' | 'OFFSET_OUT_OF_BOUNDS' | 'LENGTH_EXCEEDS_BUFFER' | 'NULL_POINTER' | 'INVALID_RANGE' | 'INVALID_PARAMETER' | 'OUT_OF_MEMORY' | 'ALLOCATION_TOO_LARGE' | 'ALLOCATOR_EXHAUSTED' | 'ALLOCATION_FAILED' | 'DOUBLE_FREE' | 'USE_AFTER_FREE' | 'LIBRARY_NOT_FOUND' | 'ABI_MISMATCH' | 'FFI_ERROR' | 'UNKNOWN';
+/** Typed Hyperdiff error — a ResultError with a HyperdiffErrorCode. */
+export type HyperdiffError = ResultError<HyperdiffErrorCode>;
+/** Error domain derived from the numeric FFI error code range. */
+export type HyperdiffErrorDomain = 'io' | 'hash' | 'cache' | 'thread' | 'diff' | 'validation' | 'allocator' | 'unknown';
+/** Numeric error code values matching Zig errors.zig ErrorCode enum(u16). */
+export declare const HYPERDIFF_NUMERIC_CODES: {
+    readonly FILE_NOT_FOUND: 1001;
+    readonly PERMISSION_DENIED: 1002;
+    readonly FILE_READ_ERROR: 1003;
+    readonly FILE_WRITE_ERROR: 1004;
+    readonly MMAP_FAILED: 1005;
+    readonly MMAP_UNMAP_FAILED: 1006;
+    readonly FILE_TOO_LARGE: 1007;
+    readonly INVALID_PATH: 1008;
+    readonly INVALID_UTF8: 2001;
+    readonly INVALID_ENCODING: 2002;
+    readonly EMPTY_INPUT: 2003;
+    readonly HASH_MISMATCH: 2004;
+    readonly INVALID_HASH_SIZE: 2005;
+    readonly HASH_COLLISION_DETECTED: 2006;
+    readonly INVALID_CACHE: 3001;
+    readonly CACHE_CORRUPTED: 3002;
+    readonly CACHE_VERSION_MISMATCH: 3003;
+    readonly CACHE_CHECKSUM_FAILED: 3004;
+    readonly CACHE_EXPIRED: 3005;
+    readonly CACHE_INCOMPLETE: 3006;
+    readonly THREAD_SPAWN_FAILED: 4001;
+    readonly THREAD_POOL_EXHAUSTED: 4002;
+    readonly THREAD_JOIN_FAILED: 4003;
+    readonly THREAD_CANCELLED: 4004;
+    readonly THREAD_INVALID_STATE: 4005;
+    readonly THREAD_RESOURCE_LIMIT: 4006;
+    readonly INVALID_ALGORITHM: 5001;
+    readonly ALGORITHM_NOT_SUPPORTED: 5002;
+    readonly INTERNAL_ERROR: 5003;
+    readonly STACK_OVERFLOW: 5004;
+    readonly RECURSION_LIMIT_EXCEEDED: 5005;
+    readonly MIDDLE_SNAKE_NOT_FOUND: 5006;
+    readonly LCS_NOT_FOUND: 5007;
+    readonly EDIT_SCRIPT_INVALID: 5008;
+    readonly DIFF_TIMEOUT: 5009;
+    readonly DIFF_CANCELLED: 5010;
+    readonly INVALID_INPUT: 6001;
+    readonly LINE_COUNT_MISMATCH: 6002;
+    readonly OFFSET_OUT_OF_BOUNDS: 6003;
+    readonly LENGTH_EXCEEDS_BUFFER: 6004;
+    readonly NULL_POINTER: 6005;
+    readonly INVALID_RANGE: 6006;
+    readonly INVALID_PARAMETER: 6007;
+    readonly OUT_OF_MEMORY: 7001;
+    readonly ALLOCATION_TOO_LARGE: 7002;
+    readonly ALLOCATOR_EXHAUSTED: 7003;
+    readonly ALLOCATION_FAILED: 7004;
+    readonly DOUBLE_FREE: 7005;
+    readonly USE_AFTER_FREE: 7006;
+};
+/**
+ * Get the error domain from a numeric FFI error code.
+ * @param numericCode - The u16 value from DiffResult.error_code
+ * @returns The domain category
+ */
+export declare function getErrorDomain(numericCode: number): HyperdiffErrorDomain;
+/**
+ * Convert a numeric FFI error code to a string error code.
+ * @param numericCode - The u16 from DiffResult.error_code
+ * @returns String code like 'OUT_OF_MEMORY', or 'UNKNOWN'
+ */
+export declare function numericToCode(numericCode: number): HyperdiffErrorCode;
+/**
+ * Get the human-readable message for a numeric error code.
+ * @param numericCode - The u16 from DiffResult.error_code
+ * @returns Message matching errors.zig errorMessage()
+ */
+export declare function errorCodeToMessage(numericCode: number): string;
+/**
+ * Create a ResultError<HyperdiffErrorCode> from a numeric FFI error code.
+ *
+ * @param numericCode - The u16 from DiffResult.error_code
+ * @returns Structured ResultError with typed code and message
+ */
+export declare function createHyperdiffError(numericCode: number): HyperdiffError;
+/**
+ * Create a ResultError for engine-level errors (not from Zig FFI).
+ *
+ * @param code - Engine error code (e.g., 'ABI_MISMATCH', 'FFI_ERROR')
+ * @param message - Human-readable description
+ * @param cause - Optional underlying Error
+ * @returns Structured ResultError
+ */
+export declare function createEngineError(code: 'LIBRARY_NOT_FOUND' | 'ABI_MISMATCH' | 'FFI_ERROR' | 'UNKNOWN', message: string, cause?: Error): HyperdiffError;

package/dist/errors.js

@@ -0,0 +1,163 @@
+import { resultError } from "@mks2508/no-throw";
+//#region src/errors.ts
+/** Numeric error code values matching Zig errors.zig ErrorCode enum(u16). */
+const HYPERDIFF_NUMERIC_CODES = {
+	FILE_NOT_FOUND: 1001,
+	PERMISSION_DENIED: 1002,
+	FILE_READ_ERROR: 1003,
+	FILE_WRITE_ERROR: 1004,
+	MMAP_FAILED: 1005,
+	MMAP_UNMAP_FAILED: 1006,
+	FILE_TOO_LARGE: 1007,
+	INVALID_PATH: 1008,
+	INVALID_UTF8: 2001,
+	INVALID_ENCODING: 2002,
+	EMPTY_INPUT: 2003,
+	HASH_MISMATCH: 2004,
+	INVALID_HASH_SIZE: 2005,
+	HASH_COLLISION_DETECTED: 2006,
+	INVALID_CACHE: 3001,
+	CACHE_CORRUPTED: 3002,
+	CACHE_VERSION_MISMATCH: 3003,
+	CACHE_CHECKSUM_FAILED: 3004,
+	CACHE_EXPIRED: 3005,
+	CACHE_INCOMPLETE: 3006,
+	THREAD_SPAWN_FAILED: 4001,
+	THREAD_POOL_EXHAUSTED: 4002,
+	THREAD_JOIN_FAILED: 4003,
+	THREAD_CANCELLED: 4004,
+	THREAD_INVALID_STATE: 4005,
+	THREAD_RESOURCE_LIMIT: 4006,
+	INVALID_ALGORITHM: 5001,
+	ALGORITHM_NOT_SUPPORTED: 5002,
+	INTERNAL_ERROR: 5003,
+	STACK_OVERFLOW: 5004,
+	RECURSION_LIMIT_EXCEEDED: 5005,
+	MIDDLE_SNAKE_NOT_FOUND: 5006,
+	LCS_NOT_FOUND: 5007,
+	EDIT_SCRIPT_INVALID: 5008,
+	DIFF_TIMEOUT: 5009,
+	DIFF_CANCELLED: 5010,
+	INVALID_INPUT: 6001,
+	LINE_COUNT_MISMATCH: 6002,
+	OFFSET_OUT_OF_BOUNDS: 6003,
+	LENGTH_EXCEEDS_BUFFER: 6004,
+	NULL_POINTER: 6005,
+	INVALID_RANGE: 6006,
+	INVALID_PARAMETER: 6007,
+	OUT_OF_MEMORY: 7001,
+	ALLOCATION_TOO_LARGE: 7002,
+	ALLOCATOR_EXHAUSTED: 7003,
+	ALLOCATION_FAILED: 7004,
+	DOUBLE_FREE: 7005,
+	USE_AFTER_FREE: 7006
+};
+/** Human-readable messages matching errors.zig errorMessage() 1:1. */
+const ERROR_MESSAGES = {
+	1001: "File not found",
+	1002: "Permission denied",
+	1003: "Failed to read file",
+	1004: "Failed to write file",
+	1005: "Memory mapping failed",
+	1006: "Failed to unmap memory",
+	1007: "File too large",
+	1008: "Invalid file path",
+	2001: "Invalid UTF-8 sequence",
+	2002: "Invalid text encoding",
+	2003: "Input is empty",
+	2004: "Hash mismatch detected",
+	2005: "Invalid hash size",
+	2006: "Hash collision detected",
+	3001: "Invalid cache structure",
+	3002: "Cache data is corrupted",
+	3003: "Cache version mismatch",
+	3004: "Cache checksum verification failed",
+	3005: "Cache has expired",
+	3006: "Cache data is incomplete",
+	4001: "Failed to spawn thread",
+	4002: "Thread pool exhausted",
+	4003: "Failed to join thread",
+	4004: "Thread was cancelled",
+	4005: "Thread in invalid state",
+	4006: "Thread resource limit reached",
+	5001: "Invalid algorithm specified",
+	5002: "Algorithm not supported",
+	5003: "Internal error occurred",
+	5004: "Stack overflow in diff algorithm",
+	5005: "Recursion limit exceeded",
+	5006: "Middle snake not found",
+	5007: "LCS not found",
+	5008: "Edit script is invalid",
+	5009: "Diff computation timed out",
+	5010: "Diff computation was cancelled",
+	6001: "Invalid input provided",
+	6002: "Line count mismatch",
+	6003: "Offset is out of bounds",
+	6004: "Length exceeds buffer size",
+	6005: "Null pointer provided",
+	6006: "Invalid range specified",
+	6007: "Invalid parameter",
+	7001: "Out of memory",
+	7002: "Allocation too large",
+	7003: "Allocator exhausted",
+	7004: "Memory allocation failed",
+	7005: "Double free detected",
+	7006: "Use after free detected"
+};
+/** Reverse lookup: numeric code → string code. */
+const NUMERIC_TO_STRING = Object.fromEntries(Object.entries(HYPERDIFF_NUMERIC_CODES).map(([k, v]) => [v, k]));
+/**
+* Get the error domain from a numeric FFI error code.
+* @param numericCode - The u16 value from DiffResult.error_code
+* @returns The domain category
+*/
+function getErrorDomain(numericCode) {
+	if (numericCode >= 1e3 && numericCode < 1100) return "io";
+	if (numericCode >= 2e3 && numericCode < 2100) return "hash";
+	if (numericCode >= 3e3 && numericCode < 3100) return "cache";
+	if (numericCode >= 4e3 && numericCode < 4100) return "thread";
+	if (numericCode >= 5e3 && numericCode < 5100) return "diff";
+	if (numericCode >= 6e3 && numericCode < 6100) return "validation";
+	if (numericCode >= 7e3 && numericCode < 7100) return "allocator";
+	return "unknown";
+}
+/**
+* Convert a numeric FFI error code to a string error code.
+* @param numericCode - The u16 from DiffResult.error_code
+* @returns String code like 'OUT_OF_MEMORY', or 'UNKNOWN'
+*/
+function numericToCode(numericCode) {
+	return NUMERIC_TO_STRING[numericCode] ?? "UNKNOWN";
+}
+/**
+* Get the human-readable message for a numeric error code.
+* @param numericCode - The u16 from DiffResult.error_code
+* @returns Message matching errors.zig errorMessage()
+*/
+function errorCodeToMessage(numericCode) {
+	return ERROR_MESSAGES[numericCode] ?? `Unknown error (code: ${numericCode})`;
+}
+/**
+* Create a ResultError<HyperdiffErrorCode> from a numeric FFI error code.
+*
+* @param numericCode - The u16 from DiffResult.error_code
+* @returns Structured ResultError with typed code and message
+*/
+function createHyperdiffError(numericCode) {
+	return resultError(numericToCode(numericCode), errorCodeToMessage(numericCode));
+}
+/**
+* Create a ResultError for engine-level errors (not from Zig FFI).
+*
+* @param code - Engine error code (e.g., 'ABI_MISMATCH', 'FFI_ERROR')
+* @param message - Human-readable description
+* @param cause - Optional underlying Error
+* @returns Structured ResultError
+*/
+function createEngineError(code, message, cause) {
+	return resultError(code, message, cause);
+}
+//#endregion
+export { HYPERDIFF_NUMERIC_CODES, createEngineError, createHyperdiffError, errorCodeToMessage, getErrorDomain, numericToCode };
+
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error handling for the Hyperdiff engine.\n *\n * Maps FFI error codes (u16 from errors.zig ErrorCode enum)\n * to structured ResultError<HyperdiffErrorCode> from @mks2508/no-throw.\n *\n * Every error code, message, and domain is 1:1 with errors.zig.\n */\nimport type { ResultError } from '@mks2508/no-throw';\nimport { resultError } from '@mks2508/no-throw';\n\n// ── Error Code String Literals ────────────────────────────────────────\n// These are the string codes used in ResultError<C>. Named to match\n// the Zig error set names for traceability.\n\n/** All valid Hyperdiff error code string literals. */\nexport type HyperdiffErrorCode =\n  // IO (1000-1099)\n  | 'FILE_NOT_FOUND'\n  | 'PERMISSION_DENIED'\n  | 'FILE_READ_ERROR'\n  | 'FILE_WRITE_ERROR'\n  | 'MMAP_FAILED'\n  | 'MMAP_UNMAP_FAILED'\n  | 'FILE_TOO_LARGE'\n  | 'INVALID_PATH'\n  // Hash (2000-2099)\n  | 'INVALID_UTF8'\n  | 'INVALID_ENCODING'\n  | 'EMPTY_INPUT'\n  | 'HASH_MISMATCH'\n  | 'INVALID_HASH_SIZE'\n  | 'HASH_COLLISION_DETECTED'\n  // Cache (3000-3099)\n  | 'INVALID_CACHE'\n  | 'CACHE_CORRUPTED'\n  | 'CACHE_VERSION_MISMATCH'\n  | 'CACHE_CHECKSUM_FAILED'\n  | 'CACHE_EXPIRED'\n  | 'CACHE_INCOMPLETE'\n  // Thread (4000-4099)\n  | 'THREAD_SPAWN_FAILED'\n  | 'THREAD_POOL_EXHAUSTED'\n  | 'THREAD_JOIN_FAILED'\n  | 'THREAD_CANCELLED'\n  | 'THREAD_INVALID_STATE'\n  | 'THREAD_RESOURCE_LIMIT'\n  // Diff (5000-5099)\n  | 'INVALID_ALGORITHM'\n  | 'ALGORITHM_NOT_SUPPORTED'\n  | 'INTERNAL_ERROR'\n  | 'STACK_OVERFLOW'\n  | 'RECURSION_LIMIT_EXCEEDED'\n  | 'MIDDLE_SNAKE_NOT_FOUND'\n  | 'LCS_NOT_FOUND'\n  | 'EDIT_SCRIPT_INVALID'\n  | 'DIFF_TIMEOUT'\n  | 'DIFF_CANCELLED'\n  // Validation (6000-6099)\n  | 'INVALID_INPUT'\n  | 'LINE_COUNT_MISMATCH'\n  | 'OFFSET_OUT_OF_BOUNDS'\n  | 'LENGTH_EXCEEDS_BUFFER'\n  | 'NULL_POINTER'\n  | 'INVALID_RANGE'\n  | 'INVALID_PARAMETER'\n  // Allocator (7000-7099)\n  | 'OUT_OF_MEMORY'\n  | 'ALLOCATION_TOO_LARGE'\n  | 'ALLOCATOR_EXHAUSTED'\n  | 'ALLOCATION_FAILED'\n  | 'DOUBLE_FREE'\n  | 'USE_AFTER_FREE'\n  // Engine-level (not from Zig)\n  | 'LIBRARY_NOT_FOUND'\n  | 'ABI_MISMATCH'\n  | 'FFI_ERROR'\n  | 'UNKNOWN';\n\n/** Typed Hyperdiff error — a ResultError with a HyperdiffErrorCode. */\nexport type HyperdiffError = ResultError<HyperdiffErrorCode>;\n\n/** Error domain derived from the numeric FFI error code range. */\nexport type HyperdiffErrorDomain =\n  | 'io'\n  | 'hash'\n  | 'cache'\n  | 'thread'\n  | 'diff'\n  | 'validation'\n  | 'allocator'\n  | 'unknown';\n\n// ── Numeric Code ↔ String Code Mapping ────────────────────────────────\n// Maps the u16 values from errors.zig ErrorCode enum to string literals.\n\n/** Numeric error code values matching Zig errors.zig ErrorCode enum(u16). */\nexport const HYPERDIFF_NUMERIC_CODES = {\n  // IO (1000-1099)\n  FILE_NOT_FOUND: 1001,\n  PERMISSION_DENIED: 1002,\n  FILE_READ_ERROR: 1003,\n  FILE_WRITE_ERROR: 1004,\n  MMAP_FAILED: 1005,\n  MMAP_UNMAP_FAILED: 1006,\n  FILE_TOO_LARGE: 1007,\n  INVALID_PATH: 1008,\n  // Hash (2000-2099)\n  INVALID_UTF8: 2001,\n  INVALID_ENCODING: 2002,\n  EMPTY_INPUT: 2003,\n  HASH_MISMATCH: 2004,\n  INVALID_HASH_SIZE: 2005,\n  HASH_COLLISION_DETECTED: 2006,\n  // Cache (3000-3099)\n  INVALID_CACHE: 3001,\n  CACHE_CORRUPTED: 3002,\n  CACHE_VERSION_MISMATCH: 3003,\n  CACHE_CHECKSUM_FAILED: 3004,\n  CACHE_EXPIRED: 3005,\n  CACHE_INCOMPLETE: 3006,\n  // Thread (4000-4099)\n  THREAD_SPAWN_FAILED: 4001,\n  THREAD_POOL_EXHAUSTED: 4002,\n  THREAD_JOIN_FAILED: 4003,\n  THREAD_CANCELLED: 4004,\n  THREAD_INVALID_STATE: 4005,\n  THREAD_RESOURCE_LIMIT: 4006,\n  // Diff (5000-5099)\n  INVALID_ALGORITHM: 5001,\n  ALGORITHM_NOT_SUPPORTED: 5002,\n  INTERNAL_ERROR: 5003,\n  STACK_OVERFLOW: 5004,\n  RECURSION_LIMIT_EXCEEDED: 5005,\n  MIDDLE_SNAKE_NOT_FOUND: 5006,\n  LCS_NOT_FOUND: 5007,\n  EDIT_SCRIPT_INVALID: 5008,\n  DIFF_TIMEOUT: 5009,\n  DIFF_CANCELLED: 5010,\n  // Validation (6000-6099)\n  INVALID_INPUT: 6001,\n  LINE_COUNT_MISMATCH: 6002,\n  OFFSET_OUT_OF_BOUNDS: 6003,\n  LENGTH_EXCEEDS_BUFFER: 6004,\n  NULL_POINTER: 6005,\n  INVALID_RANGE: 6006,\n  INVALID_PARAMETER: 6007,\n  // Allocator (7000-7099)\n  OUT_OF_MEMORY: 7001,\n  ALLOCATION_TOO_LARGE: 7002,\n  ALLOCATOR_EXHAUSTED: 7003,\n  ALLOCATION_FAILED: 7004,\n  DOUBLE_FREE: 7005,\n  USE_AFTER_FREE: 7006,\n} as const satisfies Record<string, number>;\n\n/** Human-readable messages matching errors.zig errorMessage() 1:1. */\nconst ERROR_MESSAGES: Record<number, string> = {\n  // IO\n  1001: 'File not found',\n  1002: 'Permission denied',\n  1003: 'Failed to read file',\n  1004: 'Failed to write file',\n  1005: 'Memory mapping failed',\n  1006: 'Failed to unmap memory',\n  1007: 'File too large',\n  1008: 'Invalid file path',\n  // Hash\n  2001: 'Invalid UTF-8 sequence',\n  2002: 'Invalid text encoding',\n  2003: 'Input is empty',\n  2004: 'Hash mismatch detected',\n  2005: 'Invalid hash size',\n  2006: 'Hash collision detected',\n  // Cache\n  3001: 'Invalid cache structure',\n  3002: 'Cache data is corrupted',\n  3003: 'Cache version mismatch',\n  3004: 'Cache checksum verification failed',\n  3005: 'Cache has expired',\n  3006: 'Cache data is incomplete',\n  // Thread\n  4001: 'Failed to spawn thread',\n  4002: 'Thread pool exhausted',\n  4003: 'Failed to join thread',\n  4004: 'Thread was cancelled',\n  4005: 'Thread in invalid state',\n  4006: 'Thread resource limit reached',\n  // Diff\n  5001: 'Invalid algorithm specified',\n  5002: 'Algorithm not supported',\n  5003: 'Internal error occurred',\n  5004: 'Stack overflow in diff algorithm',\n  5005: 'Recursion limit exceeded',\n  5006: 'Middle snake not found',\n  5007: 'LCS not found',\n  5008: 'Edit script is invalid',\n  5009: 'Diff computation timed out',\n  5010: 'Diff computation was cancelled',\n  // Validation\n  6001: 'Invalid input provided',\n  6002: 'Line count mismatch',\n  6003: 'Offset is out of bounds',\n  6004: 'Length exceeds buffer size',\n  6005: 'Null pointer provided',\n  6006: 'Invalid range specified',\n  6007: 'Invalid parameter',\n  // Allocator\n  7001: 'Out of memory',\n  7002: 'Allocation too large',\n  7003: 'Allocator exhausted',\n  7004: 'Memory allocation failed',\n  7005: 'Double free detected',\n  7006: 'Use after free detected',\n};\n\n/** Reverse lookup: numeric code → string code. */\nconst NUMERIC_TO_STRING: Record<number, HyperdiffErrorCode> = Object.fromEntries(\n  Object.entries(HYPERDIFF_NUMERIC_CODES).map(([k, v]) => [v, k as HyperdiffErrorCode]),\n) as Record<number, HyperdiffErrorCode>;\n\n/**\n * Get the error domain from a numeric FFI error code.\n * @param numericCode - The u16 value from DiffResult.error_code\n * @returns The domain category\n */\nexport function getErrorDomain(numericCode: number): HyperdiffErrorDomain {\n  if (numericCode >= 1000 && numericCode < 1100) return 'io';\n  if (numericCode >= 2000 && numericCode < 2100) return 'hash';\n  if (numericCode >= 3000 && numericCode < 3100) return 'cache';\n  if (numericCode >= 4000 && numericCode < 4100) return 'thread';\n  if (numericCode >= 5000 && numericCode < 5100) return 'diff';\n  if (numericCode >= 6000 && numericCode < 6100) return 'validation';\n  if (numericCode >= 7000 && numericCode < 7100) return 'allocator';\n  return 'unknown';\n}\n\n/**\n * Convert a numeric FFI error code to a string error code.\n * @param numericCode - The u16 from DiffResult.error_code\n * @returns String code like 'OUT_OF_MEMORY', or 'UNKNOWN'\n */\nexport function numericToCode(numericCode: number): HyperdiffErrorCode {\n  return NUMERIC_TO_STRING[numericCode] ?? 'UNKNOWN';\n}\n\n/**\n * Get the human-readable message for a numeric error code.\n * @param numericCode - The u16 from DiffResult.error_code\n * @returns Message matching errors.zig errorMessage()\n */\nexport function errorCodeToMessage(numericCode: number): string {\n  return ERROR_MESSAGES[numericCode] ?? `Unknown error (code: ${numericCode})`;\n}\n\n/**\n * Create a ResultError<HyperdiffErrorCode> from a numeric FFI error code.\n *\n * @param numericCode - The u16 from DiffResult.error_code\n * @returns Structured ResultError with typed code and message\n */\nexport function createHyperdiffError(numericCode: number): HyperdiffError {\n  const code = numericToCode(numericCode);\n  const message = errorCodeToMessage(numericCode);\n  return resultError(code, message);\n}\n\n/**\n * Create a ResultError for engine-level errors (not from Zig FFI).\n *\n * @param code - Engine error code (e.g., 'ABI_MISMATCH', 'FFI_ERROR')\n * @param message - Human-readable description\n * @param cause - Optional underlying Error\n * @returns Structured ResultError\n */\nexport function createEngineError(\n  code: 'LIBRARY_NOT_FOUND' | 'ABI_MISMATCH' | 'FFI_ERROR' | 'UNKNOWN',\n  message: string,\n  cause?: Error,\n): HyperdiffError {\n  return resultError(code, message, cause);\n}\n"],"mappings":";;;AAiGA,MAAa,0BAA0B;CAErC,gBAAgB;CAChB,mBAAmB;CACnB,iBAAiB;CACjB,kBAAkB;CAClB,aAAa;CACb,mBAAmB;CACnB,gBAAgB;CAChB,cAAc;CAEd,cAAc;CACd,kBAAkB;CAClB,aAAa;CACb,eAAe;CACf,mBAAmB;CACnB,yBAAyB;CAEzB,eAAe;CACf,iBAAiB;CACjB,wBAAwB;CACxB,uBAAuB;CACvB,eAAe;CACf,kBAAkB;CAElB,qBAAqB;CACrB,uBAAuB;CACvB,oBAAoB;CACpB,kBAAkB;CAClB,sBAAsB;CACtB,uBAAuB;CAEvB,mBAAmB;CACnB,yBAAyB;CACzB,gBAAgB;CAChB,gBAAgB;CAChB,0BAA0B;CAC1B,wBAAwB;CACxB,eAAe;CACf,qBAAqB;CACrB,cAAc;CACd,gBAAgB;CAEhB,eAAe;CACf,qBAAqB;CACrB,sBAAsB;CACtB,uBAAuB;CACvB,cAAc;CACd,eAAe;CACf,mBAAmB;CAEnB,eAAe;CACf,sBAAsB;CACtB,qBAAqB;CACrB,mBAAmB;CACnB,aAAa;CACb,gBAAgB;CACjB;;AAGD,MAAM,iBAAyC;CAE7C,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CAEN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CAEN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CAEN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CAEN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CAEN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CAEN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACP;;AAGD,MAAM,oBAAwD,OAAO,YACnE,OAAO,QAAQ,wBAAwB,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,EAAwB,CAAC,CACtF;;;;;;AAOD,SAAgB,eAAe,aAA2C;AACxE,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,KAAI,eAAe,OAAQ,cAAc,KAAM,QAAO;AACtD,QAAO;;;;;;;AAQT,SAAgB,cAAc,aAAyC;AACrE,QAAO,kBAAkB,gBAAgB;;;;;;;AAQ3C,SAAgB,mBAAmB,aAA6B;AAC9D,QAAO,eAAe,gBAAgB,wBAAwB,YAAY;;;;;;;;AAS5E,SAAgB,qBAAqB,aAAqC;AAGxE,QAAO,YAFM,cAAc,YAAY,EACvB,mBAAmB,YAAY,CACd;;;;;;;;;;AAWnC,SAAgB,kBACd,MACA,SACA,OACgB;AAChB,QAAO,YAAY,MAAM,SAAS,MAAM"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './result';
+export * from './errors';
+export * from './types';
+export { createLogger } from './logger';

package/dist/index.js

@@ -0,0 +1,4 @@
+import { UNKNOWN_ERROR, all, collect, createCancelledOp, createFailedOp, createFailedState, createIdleOp, createInitialState, createLoadingState, createPendingOp, createRevalidatingState, createSuccessOp, createSuccessState, err, fail, flatMap, fromPromise, hasData, isErr, isFailed, isInitial, isLoading, isOk, isOpActive, isOpCancelled, isOpDone, isOpFailed, isOpIdle, isOpPending, isOpSuccess, isPending, isRevalidating, isSuccess, map, mapErr, match, ok, opDuration, opElapsed, resultError, tap, tapErr, tryCatch, tryCatchAsync, unwrap, unwrapOr, unwrapOrElse } from "./result.js";
+import { HYPERDIFF_NUMERIC_CODES, createEngineError, createHyperdiffError, errorCodeToMessage, getErrorDomain, numericToCode } from "./errors.js";
+import { createLogger } from "./logger.js";
+export { HYPERDIFF_NUMERIC_CODES, UNKNOWN_ERROR, all, collect, createCancelledOp, createEngineError, createFailedOp, createFailedState, createHyperdiffError, createIdleOp, createInitialState, createLoadingState, createLogger, createPendingOp, createRevalidatingState, createSuccessOp, createSuccessState, err, errorCodeToMessage, fail, flatMap, fromPromise, getErrorDomain, hasData, isErr, isFailed, isInitial, isLoading, isOk, isOpActive, isOpCancelled, isOpDone, isOpFailed, isOpIdle, isOpPending, isOpSuccess, isPending, isRevalidating, isSuccess, map, mapErr, match, numericToCode, ok, opDuration, opElapsed, resultError, tap, tapErr, tryCatch, tryCatchAsync, unwrap, unwrapOr, unwrapOrElse };

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Create a scoped logger for a Hyperdiff component.
+ * @param component - Component name (e.g., 'FFI', 'Engine', 'BunAdapter')
+ * @returns Scoped logger instance
+ */
+export declare function createLogger(component: string): import("@mks2508/better-logger").ComponentLogger;

package/dist/logger.js

@@ -0,0 +1,19 @@
+import logger from "@mks2508/better-logger";
+//#region src/logger.ts
+/**
+* Logger wrapper for Hyperdiff packages.
+*
+* Re-exports from @mks2508/better-logger with a preset component prefix.
+*/
+/**
+* Create a scoped logger for a Hyperdiff component.
+* @param component - Component name (e.g., 'FFI', 'Engine', 'BunAdapter')
+* @returns Scoped logger instance
+*/
+function createLogger(component) {
+	return logger.component(`hyperdiff:${component}`);
+}
+//#endregion
+export { createLogger };
+
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","names":[],"sources":["../src/logger.ts"],"sourcesContent":["/**\n * Logger wrapper for Hyperdiff packages.\n *\n * Re-exports from @mks2508/better-logger with a preset component prefix.\n */\nimport logger from '@mks2508/better-logger';\n\n/**\n * Create a scoped logger for a Hyperdiff component.\n * @param component - Component name (e.g., 'FFI', 'Engine', 'BunAdapter')\n * @returns Scoped logger instance\n */\nexport function createLogger(component: string) {\n  return logger.component(`hyperdiff:${component}`);\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,aAAa,WAAmB;AAC9C,QAAO,OAAO,UAAU,aAAa,YAAY"}

package/dist/result.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Result pattern re-exports from @mks2508/no-throw v0.2.0.
+ *
+ * Exposes the full API: Result type, constructors, guards, transforms,
+ * pattern matching, collection ops, exception wrapping, TransactionState,
+ * and OperationState.
+ */
+export { ok, err, fail, resultError, UNKNOWN_ERROR, } from '@mks2508/no-throw';
+export type { Result, Ok, Err, ResultError, ErrorCode, } from '@mks2508/no-throw';
+export { isOk, isErr } from '@mks2508/no-throw';
+export { unwrap, unwrapOr, unwrapOrElse } from '@mks2508/no-throw';
+export { map, mapErr, flatMap } from '@mks2508/no-throw';
+export { tap, tapErr } from '@mks2508/no-throw';
+export { match } from '@mks2508/no-throw';
+export { collect, all } from '@mks2508/no-throw';
+export { fromPromise, tryCatch, tryCatchAsync } from '@mks2508/no-throw';
+export type { TransactionState } from '@mks2508/no-throw';
+export { createInitialState, createLoadingState, createRevalidatingState, createSuccessState, createFailedState, isInitial, isLoading, isRevalidating, isSuccess, isFailed, isPending, hasData, } from '@mks2508/no-throw';
+export type { OperationState, OperationStatus, IOperationProgress, IProgressEvent, } from '@mks2508/no-throw';
+export { createIdleOp, createPendingOp, createSuccessOp, createFailedOp, createCancelledOp, isOpIdle, isOpPending, isOpSuccess, isOpFailed, isOpCancelled, isOpActive, isOpDone, opDuration, opElapsed, } from '@mks2508/no-throw';

package/dist/result.js

@@ -0,0 +1,2 @@
+import { UNKNOWN_ERROR, all, collect, createCancelledOp, createFailedOp, createFailedState, createIdleOp, createInitialState, createLoadingState, createPendingOp, createRevalidatingState, createSuccessOp, createSuccessState, err, fail, flatMap, fromPromise, hasData, isErr, isFailed, isInitial, isLoading, isOk, isOpActive, isOpCancelled, isOpDone, isOpFailed, isOpIdle, isOpPending, isOpSuccess, isPending, isRevalidating, isSuccess, map, mapErr, match, ok, opDuration, opElapsed, resultError, tap, tapErr, tryCatch, tryCatchAsync, unwrap, unwrapOr, unwrapOrElse } from "@mks2508/no-throw";
+export { UNKNOWN_ERROR, all, collect, createCancelledOp, createFailedOp, createFailedState, createIdleOp, createInitialState, createLoadingState, createPendingOp, createRevalidatingState, createSuccessOp, createSuccessState, err, fail, flatMap, fromPromise, hasData, isErr, isFailed, isInitial, isLoading, isOk, isOpActive, isOpCancelled, isOpDone, isOpFailed, isOpIdle, isOpPending, isOpSuccess, isPending, isRevalidating, isSuccess, map, mapErr, match, ok, opDuration, opElapsed, resultError, tap, tapErr, tryCatch, tryCatchAsync, unwrap, unwrapOr, unwrapOrElse };

package/dist/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared FFI adapter types.
+ *
+ * These types are used across all runtime-specific FFI adapters
+ * (ffi-bun, ffi-deno, napi) and the engine package.
+ */
+/**
+ * Raw FFI result before TypeScript conversion.
+ * Matches Zig DiffResult extern struct layout (16 bytes on 64-bit):
+ *   [0..8)   edits pointer (u64)
+ *   [8..12)  edit_count (u32)
+ *   [12..16) error_code (u32)
+ */
+export interface IRawDiffResult {
+    /** Pointer to the CEdit array (Zig-owned memory). */
+    editsPtr: number;
+    /** Number of edits in the array. */
+    editCount: number;
+    /** Error code: 0 = success, non-zero = HyperdiffErrorCode numeric value. */
+    errorCode: number;
+}
+/**
+ * Low-level diff edit read from CEdit pointer.
+ * Matches Zig CEdit extern struct (20 bytes):
+ *   [0]     tag (u8)
+ *   [1..4)  _pad (3 bytes)
+ *   [4..8)  old_start (u32)
+ *   [8..12) old_end (u32)
+ *   [12..16) new_start (u32)
+ *   [16..20) new_end (u32)
+ */
+export interface IRawDiffEdit {
+    tag: number;
+    oldStart: number;
+    oldEnd: number;
+    newStart: number;
+    newEnd: number;
+}
+/**
+ * Raw FFI result for metadata generation.
+ * Matches Zig MetadataResult extern struct layout.
+ */
+export interface IRawMetadataResult {
+    /** Pointer to the CHunk array (Zig-owned memory). */
+    hunksPtr: number;
+    /** Number of hunks. */
+    hunkCount: number;
+    /** Pointer to the CContent array (Zig-owned memory). */
+    contentsPtr: number;
+    /** Total number of content entries. */
+    contentCount: number;
+    /** Total rendered line count in split view (including collapsed). */
+    splitLineCount: number;
+    /** Total rendered line count in unified view (including collapsed). */
+    unifiedLineCount: number;
+    /** Total lines in old file. */
+    oldLineCount: number;
+    /** Total lines in new file. */
+    newLineCount: number;
+    /** Error code: 0 = success, non-zero = failure. */
+    errorCode: number;
+}
+/**
+ * Raw hunk metadata read from CHunk pointer.
+ * Matches Zig CHunk extern struct (64 bytes).
+ */
+export interface IRawHunk {
+    /** Unchanged lines between previous hunk end and this hunk start. */
+    collapsedBefore: number;
+    /** Starting line in new file (1-based). */
+    additionStart: number;
+    /** Total new-file lines in this hunk (context + additions). */
+    additionCount: number;
+    /** Count of added lines only. */
+    additionLines: number;
+    /** 0-based index into full new-file line array. */
+    additionLineIndex: number;
+    /** Starting line in old file (1-based). */
+    deletionStart: number;
+    /** Total old-file lines in this hunk (context + deletions). */
+    deletionCount: number;
+    /** Count of deleted lines only. */
+    deletionLines: number;
+    /** 0-based index into full old-file line array. */
+    deletionLineIndex: number;
+    /** Starting rendered line index in split view. */
+    splitLineStart: number;
+    /** Rendered line count in split view. */
+    splitLineCount: number;
+    /** Starting rendered line index in unified view. */
+    unifiedLineStart: number;
+    /** Rendered line count in unified view. */
+    unifiedLineCount: number;
+    /** Index into CContent array where this hunk's entries begin. */
+    contentOffset: number;
+    /** Number of CContent entries for this hunk. */
+    contentCount: number;
+    /** 1 if new file has no trailing newline at this hunk's end. */
+    noEofcrAdditions: number;
+    /** 1 if old file has no trailing newline at this hunk's end. */
+    noEofcrDeletions: number;
+}
+/**
+ * Raw content entry read from CContent pointer.
+ * Matches Zig CContent extern struct (20 bytes).
+ *
+ * Tag 0 = context (unchanged lines): param1 = line count, param2 = 0.
+ * Tag 1 = change: param1 = additions, param2 = deletions.
+ */
+export interface IRawContent {
+    /** 0 = context, 1 = change. */
+    tag: 0 | 1;
+    /** Context: line count. Change: number of additions. */
+    param1: number;
+    /** Context: 0. Change: number of deletions. */
+    param2: number;
+    /** 0-based index into new-file line array. */
+    additionLineIndex: number;
+    /** 0-based index into old-file line array. */
+    deletionLineIndex: number;
+}
+/**
+ * Adapter interface that runtime-specific FFI packages must implement.
+ * The engine package consumes this to provide the high-level diff() API.
+ */
+export interface IFFIAdapter {
+    /** Compute a diff between two text buffers. Returns raw pointer data. */
+    compute(oldText: string, newText: string, algorithm: number): IRawDiffResult;
+    /** Free a previously returned DiffResult's edit array. */
+    free(resultPtr: number): void;
+    /** Health check — returns 42 if library is loaded correctly. */
+    ping(): number;
+    /** Return CEdit struct size in bytes for ABI validation. */
+    ceditSize(): number;
+    /** Return ABI version for compatibility check. */
+    abiVersion(): number;
+    /** Read CEdit array from pointer into TypeScript objects. */
+    readEdits(editsPtr: number, editCount: number): IRawDiffEdit[];
+    /** Generate Pierre-compatible hunk metadata from two text buffers. */
+    metadata(oldText: string, newText: string, algorithm: number, contextLines: number, flags: number): IRawMetadataResult;
+    /** Read CHunk array from pointer into TypeScript objects. */
+    readHunks(hunksPtr: number, hunkCount: number): IRawHunk[];
+    /** Read CContent array from pointer into TypeScript objects. */
+    readContents(contentsPtr: number, contentCount: number): IRawContent[];
+    /** Free a MetadataResult previously returned by metadata(). */
+    metadataFree(hunksPtr: number, hunkCount: number, contentsPtr: number, contentCount: number): void;
+    /**
+     * Generate unified diff patch directly from two text buffers.
+     * Returns the patch string. Algorithm: 0=myers, 1=histogram, 2=onp, 255=auto.
+     */
+    patch(oldText: string, newText: string, algorithm: number, contextLines: number): string;
+    /**
+     * Compute inline (word or char level) diff between two single lines.
+     * Mode: 0=word, 1=char. Returns array of inline edits with byte offsets.
+     */
+    inlineDiff(oldLine: string, newLine: string, mode: number): IRawDiffEdit[];
+    /** Runtime identifier for debugging. */
+    readonly runtime: 'ffi-bun' | 'ffi-deno' | 'napi';
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mks2508/hyperdiff-utils",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./result": {
+      "import": "./dist/result.js",
+      "types": "./dist/result.d.ts"
+    },
+    "./logger": {
+      "import": "./dist/logger.js",
+      "types": "./dist/logger.d.ts"
+    },
+    "./errors": {
+      "import": "./dist/errors.js",
+      "types": "./dist/errors.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && ../../../node_modules/.bin/rolldown --config rolldown.config.ts && ../../../node_modules/.bin/tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "dev": "../../../node_modules/.bin/rolldown --config rolldown.config.ts --watch"
+  },
+  "dependencies": {
+    "@mks2508/better-logger": "^4.0.0",
+    "@mks2508/no-throw": "^0.2.0"
+  }
+}