@addfox/common 0.1.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 addfox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @addfox/common
+
+Shared utilities for Addfox packages.
+
+## Installation
+
+```bash
+npm install @addfox/common
+# or
+pnpm add @addfox/common
+```
+
+## Cache Utilities
+
+```typescript
+import { createCache, memoize } from '@addfox/common';
+
+// Create a cache
+const cache = createCache<string>();
+cache.set('key', 'value', 60000); // 60 second TTL
+const value = cache.get('key');
+
+// Memoize a function
+const expensiveFn = memoize((n: number) => n * n);
+expensiveFn(5); // computed
+expensiveFn(5); // cached
+```
+
+## Pipeline Utilities
+
+```typescript
+import { pipe, compose, createPipeline } from '@addfox/common';
+
+// Compose functions
+const result = pipe(
+  (x: number) => x + 1,
+  (x) => x * 2,
+  (x) => x.toString()
+)(5); // "12"
+
+// Create async pipeline
+const pipeline = createPipeline(
+  async (input: string) => input.toUpperCase(),
+  async (input) => input.split(''),
+  async (input) => input.join('-')
+);
+const result = await pipeline('hello'); // "H-E-L-L-O"
+```
+
+## Object Utilities
+
+```typescript
+import { deepMerge, pick, omit, get, set } from '@addfox/common';
+
+// Deep merge
+const merged = deepMerge({ a: { b: 1 } }, { a: { c: 2 } });
+// { a: { b: 1, c: 2 } }
+
+// Pick/omit properties
+const picked = pick({ a: 1, b: 2, c: 3 }, ['a', 'c']); // { a: 1, c: 3 }
+const omitted = omit({ a: 1, b: 2, c: 3 }, ['b']); // { a: 1, c: 3 }
+
+// Get/set nested properties
+const obj = { nested: { value: 42 } };
+const value = get(obj, 'nested.value'); // 42
+const newObj = set(obj, 'nested.other', 100);
+```
+
+## Error Utilities
+
+```typescript
+import { AddfoxError, createError, formatError } from '@addfox/common';
+
+// Create error
+const error = createError('CONFIG_ERROR', 'Failed to load config', {
+  details: 'File not found',
+  hint: 'Check the file path',
+});
+
+// Format error
+console.log(formatError(error));
+// [CONFIG_ERROR] Failed to load config
+//   Details: File not found
+//   Hint: Check the file path
+```
+
+## Types
+
+```typescript
+import type { 
+  Logger, 
+  Result, 
+  ValidationResult,
+  Strategy,
+  Pipeline,
+  Middleware 
+} from '@addfox/common';
+```
+
+## License
+
+MIT

package/dist/cjs/errors/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @addfox/common/errors
+ * Unified error system with error codes and formatting
+ */
+export declare const ADDFOX_ERROR_CODES: {
+    readonly CONFIG_NOT_FOUND: "ADDFOX_CONFIG_NOT_FOUND";
+    readonly CONFIG_LOAD_FAILED: "ADDFOX_CONFIG_LOAD_FAILED";
+    readonly MANIFEST_MISSING: "ADDFOX_MANIFEST_MISSING";
+    readonly APP_DIR_MISSING: "ADDFOX_APP_DIR_MISSING";
+    readonly NO_ENTRIES: "ADDFOX_NO_ENTRIES";
+    readonly ENTRY_SCRIPT_FROM_HTML: "ADDFOX_ENTRY_SCRIPT_FROM_HTML";
+    readonly INVALID_BROWSER: "ADDFOX_INVALID_BROWSER";
+    readonly UNKNOWN_COMMAND: "ADDFOX_UNKNOWN_COMMAND";
+    readonly RSTEST_CONFIG_NOT_FOUND: "ADDFOX_RSTEST_CONFIG_NOT_FOUND";
+    readonly RSDOCTOR_NOT_INSTALLED: "ADDFOX_RSDOCTOR_NOT_INSTALLED";
+    readonly RSBUILD_CONFIG_ERROR: "ADDFOX_RSBUILD_CONFIG_ERROR";
+    readonly BUILD_ERROR: "ADDFOX_BUILD_ERROR";
+    readonly ZIP_OUTPUT: "ADDFOX_ZIP_OUTPUT";
+    readonly ZIP_ARCHIVE: "ADDFOX_ZIP_ARCHIVE";
+};
+export type AddfoxErrorCode = (typeof ADDFOX_ERROR_CODES)[keyof typeof ADDFOX_ERROR_CODES];
+export interface ErrorOptions {
+    code: string;
+    message: string;
+    details?: string;
+    hint?: string;
+    cause?: unknown;
+}
+export interface ErrorJSON {
+    name: string;
+    code: string;
+    message: string;
+    details?: string;
+    hint?: string;
+    stack?: string;
+    cause?: unknown;
+}
+/**
+ * Addfox base error class
+ *
+ * Provides:
+ * - Error code for programmatic handling
+ * - Details and hint for user guidance
+ * - JSON serialization
+ * - Formatted string output
+ */
+export declare class AddfoxError extends Error {
+    readonly code: string;
+    readonly details?: string;
+    readonly hint?: string;
+    readonly cause?: unknown;
+    constructor(options: ErrorOptions);
+    /**
+     * Serialize error to JSON
+     */
+    toJSON(): ErrorJSON;
+    /**
+     * Format error for display
+     */
+    format(): string;
+    /**
+     * String representation
+     */
+    toString(): string;
+}
+/**
+ * Create a generic AddfoxError
+ */
+export declare function createError(code: string, message: string, options?: Omit<ErrorOptions, "code" | "message">): AddfoxError;
+/**
+ * Check if value is an AddfoxError
+ */
+export declare function isAddfoxError(error: unknown): error is AddfoxError;
+/**
+ * Format any error for display
+ */
+export declare function formatError(error: unknown): string;
+/**
+ * Print error to stderr and exit process.
+ * Used in CLI top-level catch for clear error reporting.
+ *
+ * Note: This function should be called from CLI only, as it exits the process.
+ * The error display is handled by the caller (CLI) using logger.error().
+ */
+export declare function exitWithError(_err: unknown, exitCode?: number): never;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;CAerB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAM3F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,YAAY;IAWjC;;OAEG;IACH,MAAM,IAAI,SAAS;IAYnB;;OAEG;IACH,MAAM,IAAI,MAAM;IAOhB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB;AAMD;;GAEG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC,GAC/C,WAAW,CAEb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQlD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,KAAK,CAIhE"}

package/dist/cjs/hooks/HookManager.d.ts

@@ -0,0 +1,67 @@
+import type { HookFunction, HookPhase, HookManagerOptions } from './types.js';
+/**
+ * Generic hook manager - allows users to define their own stages
+ * Only provides before/after hooks for additional code execution
+ */
+export declare class HookManager<T extends Record<string, unknown> = Record<string, unknown>> {
+    private registry;
+    private options;
+    constructor(options?: HookManagerOptions);
+    /**
+     * Register a hook for a specific stage and phase
+     * @param stage - The stage name (user-defined)
+     * @param phase - 'before' or 'after'
+     * @param handler - The hook function
+     * @returns Unregister function
+     */
+    register<K extends keyof T>(stage: K, phase: HookPhase, handler: HookFunction<T[K]>): () => void;
+    /**
+     * Execute hooks for a specific stage and phase
+     * @param stage - The stage name
+     * @param phase - 'before' or 'after'
+     * @param payload - Data passed to hooks
+     */
+    execute<K extends keyof T>(stage: K, phase: HookPhase, payload: T[K]): Promise<void>;
+    /**
+     * Check if hooks exist for a stage/phase
+     */
+    has<K extends keyof T>(stage: K, phase: HookPhase): boolean;
+    /**
+     * Get number of registered hooks for a stage/phase
+     */
+    count<K extends keyof T>(stage: K, phase: HookPhase): number;
+    /**
+     * Clear all hooks for a stage/phase, or all hooks if no stage specified
+     */
+    clear<K extends keyof T>(stage?: K, phase?: HookPhase): void;
+    private getKey;
+    /**
+     * Get a scoped hook manager for a specific stage
+     */
+    for<K extends keyof T>(stage: K): StageHookManager<T, K>;
+}
+/**
+ * Scoped hook manager for a specific stage
+ */
+export declare class StageHookManager<T extends Record<string, unknown>, K extends keyof T> {
+    private manager;
+    private stage;
+    constructor(manager: HookManager<T>, stage: K);
+    /**
+     * Register a 'before' hook
+     */
+    before(handler: HookFunction<T[K]>): () => void;
+    /**
+     * Register an 'after' hook
+     */
+    after(handler: HookFunction<T[K]>): () => void;
+    /**
+     * Execute 'before' hooks
+     */
+    runBefore(payload: T[K]): Promise<void>;
+    /**
+     * Execute 'after' hooks
+     */
+    runAfter(payload: T[K]): Promise<void>;
+}
+//# sourceMappingURL=HookManager.d.ts.map

package/dist/cjs/hooks/HookManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HookManager.d.ts","sourceRoot":"","sources":["../../../src/hooks/HookManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClF,OAAO,CAAC,QAAQ,CAAmD;IACnE,OAAO,CAAC,OAAO,CAAqB;gBAExB,OAAO,GAAE,kBAAuB;IAQ5C;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,EACxB,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1B,MAAM,IAAI;IAmBb;;;;;OAKG;IACG,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,GACZ,OAAO,CAAC,IAAI,CAAC;IAoChB;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO;IAK3D;;OAEG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM;IAK5D;;OAEG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI;IAW5D,OAAO,CAAC,MAAM;IAId;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC;CAGzD;AAED;;GAEG;AACH,qBAAa,gBAAgB,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC;IAGf,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,KAAK;gBADL,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,KAAK,EAAE,CAAC;IAGlB;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI/C;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI9C;;OAEG;IACG,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAG7C"}

package/dist/cjs/hooks/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generic hook system - allows users to define their own stages
+ * Provides only before/after hooks for additional code execution
+ */
+export { HookManager, StageHookManager } from './HookManager.js';
+export type { HookFunction, HookRegistry, HookPhase, HookDescriptor, HookManagerOptions, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACjE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/cjs/hooks/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hook types for the generic hook system
+ */
+/** Base hook function type */
+export type HookFunction<T = void> = T extends void ? () => void | Promise<void> : (payload: T) => void | Promise<void>;
+/** Hook registry - stores hooks by name */
+export type HookRegistry<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: Array<HookFunction<T[K]>>;
+};
+/** Hook phase types */
+export type HookPhase = 'before' | 'after';
+/** Hook descriptor */
+export interface HookDescriptor<T = unknown> {
+    name: string;
+    phase: HookPhase;
+    handler: HookFunction<T>;
+    priority?: number;
+}
+/** Hook manager options */
+export interface HookManagerOptions {
+    /** Whether to run hooks in parallel (default: false - sequential) */
+    parallel?: boolean;
+    /** Whether to stop on first error (default: false) */
+    bail?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/hooks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/hooks/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,8BAA8B;AAC9B,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,SAAS,IAAI,GAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC1B,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzC,2CAA2C;AAC3C,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;KACrF,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3C,CAAC;AAEF,uBAAuB;AACvB,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3C,sBAAsB;AACtB,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2BAA2B;AAC3B,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB"}