@decohere/core 0.0.1-dev.116

package/es6/src/semver/semver.js

@@ -0,0 +1,71 @@
+export const VersionTypes = {
+    major: "major",
+    minor: "minor",
+    patch: "patch",
+    prerelease: "prerelease"
+};
+export class SemverError extends Error {
+    constructor(message){
+        super(message);
+        this.name = SemverError.name;
+    }
+}
+const SEMVER_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+export class Semver {
+    version;
+    constructor(version){
+        this.ensureValid(version);
+        this.version = version;
+    }
+    increment(versionType, preid = "pre") {
+        const { major, minor, patch, prerelease } = this.parse(this.version);
+        if (versionType === "major") {
+            this.version = `${major + 1}.0.0`;
+            return this;
+        }
+        if (versionType === "minor") {
+            this.version = `${major}.${minor + 1}.0`;
+            return this;
+        }
+        if (versionType === "patch") {
+            this.version = `${major}.${minor}.${patch + 1}`;
+            return this;
+        }
+        if (prerelease == null) {
+            this.version = `${major}.${minor}.${patch + 1}-${preid}.0`;
+            return this;
+        }
+        const [identifier, ...rest] = prerelease.split(".");
+        const maybeCounter = rest.at(-1);
+        const counter = maybeCounter != null ? Number.parseInt(maybeCounter, 10) : Number.NaN;
+        if (identifier === preid && Number.isFinite(counter)) {
+            const nextCounter = counter + 1;
+            const prefix = rest.length > 1 ? `${rest.slice(0, -1).join(".")}.` : "";
+            this.version = `${major}.${minor}.${patch}-${preid}.${prefix}${nextCounter}`;
+            return this;
+        }
+        this.version = `${major}.${minor}.${patch}-${preid}.0`;
+        return this;
+    }
+    toString() {
+        return this.version;
+    }
+    ensureValid(version) {
+        if (SEMVER_REGEX.test(version)) {
+            return;
+        }
+        throw new SemverError(`Invalid semantic version: ${version}`);
+    }
+    parse(version) {
+        const match = version.match(SEMVER_REGEX);
+        if (match == null) {
+            throw new SemverError(`Invalid semantic version: ${version}`);
+        }
+        return {
+            major: Number.parseInt(match[1], 10),
+            minor: Number.parseInt(match[2], 10),
+            patch: Number.parseInt(match[3], 10),
+            prerelease: match[4]
+        };
+    }
+}

package/es6/src/system/camel-case.js

@@ -0,0 +1,3 @@
+export function lowerCamelCase(val) {
+    return String(val).charAt(0).toLowerCase() + String(val).slice(1);
+}

package/es6/src/system/debounce.js

@@ -0,0 +1,9 @@
+export function debounce(callback, delay) {
+    let timeoutTimer;
+    return (...args)=>{
+        clearTimeout(timeoutTimer);
+        timeoutTimer = setTimeout(async ()=>{
+            await callback(...args);
+        }, delay);
+    };
+}

package/es6/src/system/decorator.js

@@ -0,0 +1,30 @@
+export class FunctionDecorator {
+    options;
+    constructor(){
+        this.decoratorFactory = this.decoratorFactory.bind(this);
+    }
+    decoratorFactory(options) {
+        this.options = options;
+        return this.decorator.bind(this);
+    }
+}
+/**
+ * Skips the decorated method decorator if any of the named environment variables equal "true".
+ * Useful for disabling decorators like @cache() during unit tests or via feature flags.
+ *
+ * @example @ignoreIf("TEST", "DISABLE_CACHE")
+ */ export function ignoreIf(...envVars) {
+    return (_, __, descriptor)=>{
+        const originalFunction = descriptor.value;
+        descriptor.value = function(target, key, descriptor) {
+            if (envVars.some((v)=>process.env[v] === "true")) {
+                return descriptor;
+            }
+            return originalFunction.bind(this)(target, key, descriptor);
+        };
+        return descriptor;
+    };
+}
+/** @deprecated Use ignoreIf("TEST") instead */ export function ignoreDuringUnitTest() {
+    return ignoreIf("TEST");
+}

package/es6/src/system/environment.js

@@ -0,0 +1,5 @@
+export const Environments = {
+    production: "production",
+    development: "development"
+};
+export const DefaultEnvironment = Environments.development;

package/es6/src/system/function.types.js

@@ -0,0 +1,26 @@
+/**
+ * Generic function type that can replace arrow function signatures.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: (arg1: string, arg2: number) => boolean
+ * type MyCallback = Func<[string, number], boolean>;
+ *
+ * // Instead of: (data: any) => void
+ * type MyHandler = Func<[any], void>;
+ *
+ * // Instead of: () => Promise<string>
+ * type MyAsyncFunc = Func<[], Promise<string>>;
+ * ```
+ */ /**
+ * Action function type that returns void.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: (event: Event) => void
+ * type EventHandler = Action<[Event]>;
+ *
+ * // Instead of: () => void
+ * type Callback = Action<[]>;
+ * ```
+ */ export { };

package/es6/src/system/index.js

@@ -0,0 +1,7 @@
+export * from "./camel-case.js";
+export * from "./debounce.js";
+export * from "./decorator.js";
+export * from "./environment.js";
+export * from "./function.types.js";
+export * from "./retry.decorator.js";
+export * from "./type.utils.js";

package/es6/src/system/retry.decorator.js

@@ -0,0 +1,30 @@
+import { FunctionDecorator } from "./decorator.js";
+import { sleep } from "./sleep.js";
+class RetryDecorator extends FunctionDecorator {
+    decorator(_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const attempts = Math.max(1, this.options?.attempts ?? 3);
+        const delayMs = Math.max(0, this.options?.delayMs ?? 0);
+        const shouldRetry = this.options?.shouldRetry ?? (()=>true);
+        descriptor.value = async function(...args) {
+            let lastError;
+            for(let attempt = 1; attempt <= attempts; attempt++){
+                try {
+                    return await Promise.resolve(originalMethod.apply(this, args));
+                } catch (error) {
+                    lastError = error;
+                    const shouldAttemptAgain = attempt < attempts && shouldRetry(error);
+                    if (!shouldAttemptAgain) {
+                        throw error;
+                    }
+                    if (delayMs > 0) {
+                        await sleep(delayMs);
+                    }
+                }
+            }
+            throw lastError;
+        };
+        return descriptor;
+    }
+}
+export const retry = new RetryDecorator().decoratorFactory;

package/es6/src/system/sleep.js

@@ -0,0 +1,3 @@
+export const sleep = (ms)=>new Promise((resolve)=>setTimeout(()=>{
+            resolve(null);
+        }, ms));

package/es6/src/system/type.utils.js

@@ -0,0 +1 @@
+export { };

package/es6/src/testing/flush-promises.js

@@ -0,0 +1,6 @@
+var scheduler = typeof setImmediate === "function" ? setImmediate : setTimeout;
+export function flushPromises() {
+    return new Promise((resolve)=>{
+        scheduler(resolve);
+    });
+}

package/es6/src/testing/glob-with-memfs.js

@@ -0,0 +1,20 @@
+import { fs } from "memfs";
+// Wraps a real `glob` module so all file-system access is routed through memfs.
+//
+// Why this exists:
+// - Integration tests often need real glob matching semantics.
+// - Vitest `vi.mock` factories are hoisted, so directly importing and patching
+//   `glob` inside helper modules can trigger initialization-order issues.
+// - Passing the already-loaded `actual` module keeps the helper pure and
+//   hoist-safe while still allowing us to inject memfs.
+export function withMemfsFsForGlob(actual) {
+    // Preserve all module exports, overriding only `glob` to force `{ fs: memfs }`.
+    const glob = (pattern, options)=>actual.glob(pattern, {
+            ...options,
+            fs
+        });
+    return {
+        ...actual,
+        glob
+    };
+}

package/es6/src/testing/index.js

@@ -0,0 +1,5 @@
+export * from "./flush-promises.js";
+export * from "./glob-with-memfs.js";
+export * from "./memfs.js";
+export * from "./mock-logger.js";
+export * from "./spy-on-constructor.js";

package/es6/src/testing/memfs.js

@@ -0,0 +1,25 @@
+import { fs, vol } from "memfs";
+export function resetMemfs() {
+    vol.reset();
+}
+export function seedMemfs(files) {
+    vol.fromJSON(files);
+}
+export function createTestFile(filePath, content) {
+    fs.mkdirSync(filePath.substring(0, filePath.lastIndexOf("/")), {
+        recursive: true
+    });
+    fs.writeFileSync(filePath, content);
+}
+export async function readFile(filePath) {
+    const response = await fs.promises.readFile(filePath, "utf8");
+    return response;
+}
+export function fileExists(filePath) {
+    try {
+        vol.statSync(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+}

package/es6/src/testing/mock-logger.js

@@ -0,0 +1,26 @@
+import { vi } from "vitest";
+const DefaultLogLevels = {
+    fatal: 60,
+    error: 50,
+    warn: 40,
+    info: 30,
+    debug: 20,
+    trace: 10
+};
+export function createMockLogger() {
+    return {
+        error: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        debug: vi.fn(),
+        trace: vi.fn(),
+        fatal: vi.fn(),
+        isLevelEnabled: vi.fn().mockReturnValue(true),
+        get currentLevel () {
+            return "info";
+        },
+        get logLevels () {
+            return DefaultLogLevels;
+        }
+    };
+}

package/es6/src/testing/spy-on-constructor.js

@@ -0,0 +1,31 @@
+import { vi } from "vitest";
+/**
+ * Creates a Proxy around a class constructor that intercepts `new` calls,
+ * records arguments via a spy, and delegates to the real constructor.
+ *
+ * Use this to assert what was injected into a class by a DI container
+ * (e.g. Container) without changing actual behavior.
+ *
+ * The proxy copies all `reflect-metadata` entries from the original class
+ * so that DI metadata (`design:paramtypes`) remains intact.
+ *
+ * @example
+ * const { spy, Proxy: SpiedService } = spyOnConstructor(MyService);
+ * // use SpiedService in place of MyService when wiring the container
+ * expect(spy).toHaveBeenCalledWith(expect.any(ExpectedDependency));
+ */ export function spyOnConstructor(Target) {
+    const spy = vi.fn();
+    const ProxiedTarget = new Proxy(Target, {
+        construct (Ctor, args) {
+            spy(...args);
+            return Reflect.construct(Ctor, args);
+        }
+    });
+    for (const key of Reflect.getMetadataKeys(Target)){
+        Reflect.defineMetadata(key, Reflect.getMetadata(key, Target), ProxiedTarget);
+    }
+    return {
+        spy,
+        Proxy: ProxiedTarget
+    };
+}

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@decohere/core",
+  "version": "0.0.1-dev.116",
+  "description": "Core utility library — collections, caching, IO, CLI primitives, reflection, and composition",
+  "keywords": [
+    "typescript",
+    "utilities",
+    "collections",
+    "caching",
+    "io",
+    "cli",
+    "reflection",
+    "decohere"
+  ],
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    "./collections": {
+      "types": "./types/src/collections/index.d.ts",
+      "import": "./es6/src/collections/index.js",
+      "require": "./commonjs/src/collections/index.js"
+    },
+    "./caching": {
+      "types": "./types/src/caching/index.d.ts",
+      "import": "./es6/src/caching/index.js",
+      "require": "./commonjs/src/caching/index.js"
+    },
+    "./configuration": {
+      "types": "./types/src/configuration/index.d.ts",
+      "import": "./es6/src/configuration/index.js",
+      "require": "./commonjs/src/configuration/index.js"
+    },
+    "./extensibility": {
+      "types": "./types/src/extensibility/index.d.ts",
+      "import": "./es6/src/extensibility/index.js",
+      "require": "./commonjs/src/extensibility/index.js"
+    },
+    "./interop": {
+      "types": "./types/src/interop/index.d.ts",
+      "import": "./es6/src/interop/index.js",
+      "require": "./commonjs/src/interop/index.js"
+    },
+    "./io": {
+      "types": "./types/src/io/index.d.ts",
+      "import": "./es6/src/io/index.js",
+      "require": "./commonjs/src/io/index.js"
+    },
+    "./objects": {
+      "types": "./types/src/objects/index.d.ts",
+      "import": "./es6/src/objects/index.js",
+      "require": "./commonjs/src/objects/index.js"
+    },
+    "./reflection": {
+      "types": "./types/src/reflection/index.d.ts",
+      "import": "./es6/src/reflection/index.js",
+      "require": "./commonjs/src/reflection/index.js"
+    },
+    "./system": {
+      "types": "./types/src/system/index.d.ts",
+      "import": "./es6/src/system/index.js",
+      "require": "./commonjs/src/system/index.js"
+    },
+    "./semver": {
+      "types": "./types/src/semver/index.d.ts",
+      "import": "./es6/src/semver/index.js",
+      "require": "./commonjs/src/semver/index.js"
+    },
+    "./testing": {
+      "types": "./types/src/testing/index.d.ts",
+      "import": "./es6/src/testing/index.js",
+      "require": "./commonjs/src/testing/index.js"
+    },
+    "./composition": {
+      "types": "./types/src/composition/index.d.ts",
+      "import": "./es6/src/composition/index.js",
+      "require": "./commonjs/src/composition/index.js"
+    },
+    "./cli": {
+      "types": "./types/src/cli/index.d.ts",
+      "import": "./es6/src/cli/index.js",
+      "require": "./commonjs/src/cli/index.js"
+    },
+    "./diagnostics": {
+      "types": "./types/src/diagnostics/index.d.ts",
+      "import": "./es6/src/diagnostics/index.js",
+      "require": "./commonjs/src/diagnostics/index.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@cacheable/node-cache": "^2.0.1",
+    "@decohere/scribe": "0.0.1-dev.116",
+    "commander": "^13.1.0",
+    "glob": "^13.0.1",
+    "picomatch": "^4.0.4",
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "memfs": "^4.17.0",
+    "vitest": "^3.2.6"
+  }
+}

package/types/src/caching/cache-manager.d.ts

@@ -0,0 +1,59 @@
+import type { ICache } from "./cache.js";
+export declare const Caches: {
+    readonly default: "DEFAULT";
+    readonly memoize: "MEMOIZE_CACHE";
+};
+/**
+ * Central cache manager for managing named cache instances
+ */
+declare class CacheManager {
+    private caches;
+    private readonly defaultCacheName;
+    /**
+     * Set a cache instance with the given name
+     * @param name - The name of the cache
+     * @param cache - The cache instance
+     */
+    setCache(name: string, cache: ICache): void;
+    /**
+     * Get a cache instance by name
+     * @param name - The name of the cache, defaults to "DEFAULT"
+     * @returns The cache instance
+     */
+    getCache(name?: string, memoize?: boolean): ICache;
+    /**
+     * Clear a cache by name. If no name is provided, clears the default cache.
+     * Note: This only works if the cache implements a clear() method.
+     * @param name - The name of the cache to clear
+     */
+    flush(name?: string): void;
+    flushAllCaches(): void;
+    /**
+     * Remove a cache instance by name
+     * @param name - The name of the cache to remove
+     */
+    removeCache(name: string): void;
+    /**
+     * Check if a cache with the given name exists
+     * @param name - The name of the cache
+     * @returns True if the cache exists, false otherwise
+     */
+    hasCache(name: string): boolean;
+    private readonly instanceIds;
+    private instanceIdCounter;
+    /**
+     * Generate a cache key for a given instance, function name, and arguments.
+     * Each instance receives a stable numeric ID so cache entries are never
+     * shared across instances of the same class.
+     * @param instance - The class instance (`this` at call time)
+     * @param functionName - The name of the decorated method
+     * @param args - The method arguments
+     * @returns A unique cache key string
+     */
+    generateCacheKey(instance: object, functionName: string, args: unknown[]): string;
+}
+/**
+ * Singleton instance of the cache manager
+ */
+export declare const Caching: CacheManager;
+export {};

package/types/src/caching/cache.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interface for cache implementations used by the @cache() decorator
+ */
+export interface ICache {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    del(key: string): void;
+    flushAll(): any;
+    get isMemoize(): boolean;
+}

package/types/src/caching/cache.decorator.d.ts

@@ -0,0 +1,18 @@
+import { FunctionDecorator } from "../system/decorator.js";
+import type { ICache } from "./cache.js";
+/**
+ * Options for configuring the @cache() decorator
+ */
+export interface CacheOptions {
+    cache?: ICache;
+    name?: string;
+    /**
+     * Custom key function. When provided, replaces the default instance-scoped key
+     * with a caller-defined key, enabling cross-instance cache sharing.
+     */
+    keyFn?: (...args: unknown[]) => string;
+}
+export declare class CacheDecorator extends FunctionDecorator<CacheOptions> {
+    decorator(_target: object, propertyKey: string, descriptor: PropertyDescriptor): void;
+}
+export declare const cache: (options?: CacheOptions) => any;

package/types/src/caching/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./cache.decorator.js";
+export * from "./cache.js";
+export * from "./cache-manager.js";
+export * from "./invalidate-cache.decorator.js";
+export * from "./memoize.decorator.js";
+export * from "./node-cache-memoize.adapter.js";

package/types/src/caching/invalidate-cache.decorator.d.ts

@@ -0,0 +1,17 @@
+import { FunctionDecorator } from "../system/decorator.js";
+import type { CacheOptions } from "./cache.decorator.js";
+type InvalidateCacheOptions = CacheOptions & {
+    getKey: (instance: object, args: unknown[]) => string;
+};
+export declare class InvalidateCacheDecorator extends FunctionDecorator<InvalidateCacheOptions> {
+    decorator(_target: object, _propertyKey: string, descriptor: PropertyDescriptor): void;
+}
+export declare const invalidateCache: {
+    (method: string | ((...args: never[]) => unknown), options?: CacheOptions): any;
+    evict(instance: object, method: (...args: never[]) => unknown, args?: unknown[]): void;
+};
+export declare const invalidateMemoize: {
+    (method: string | ((...args: never[]) => unknown), options?: CacheOptions): any;
+    evict(instance: object, method: (...args: never[]) => unknown, args?: unknown[]): void;
+};
+export {};

package/types/src/caching/memoize.decorator.d.ts

@@ -0,0 +1,16 @@
+import { CacheDecorator } from "./cache.decorator.js";
+/**
+ * Memoize decorator class that extends CacheDecorator with memoization support
+ * Automatically uses a memoization-capable cache (NodeCache with useClones: false)
+ */
+export declare class MemoizeDecorator extends CacheDecorator {
+    decorator(target: object, propertyKey: string, descriptor: PropertyDescriptor): void;
+}
+/**
+ * Memoize decorator factory
+ * Provides true memoization by storing object references instead of clones
+ *
+ * @param options - Optional configuration for the memoize decorator
+ * @returns Decorator function
+ */
+export declare const memoize: (options?: import("./cache.decorator.js").CacheOptions) => any;

package/types/src/caching/node-cache-memoize.adapter.d.ts

@@ -0,0 +1,22 @@
+import NodeCache from "@cacheable/node-cache";
+import type { ICache } from "./cache.js";
+type NodeCacheMemoizeOptions = {
+    enableMemoization: boolean;
+};
+/**
+ * NodeCache adapter configured for memoization (useClones: false)
+ * This allows storing object references instead of clones for true memoization
+ */
+export declare class NodeCacheAdapter implements ICache {
+    static create(options?: NodeCacheMemoizeOptions): NodeCacheAdapter;
+    readonly supportsMemoization: true;
+    private cache;
+    constructor(inst?: NodeCache<unknown>);
+    get isMemoize(): boolean;
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    del(key: string): void;
+    flushAll(): void;
+}
+export {};

package/types/src/cli/action.d.ts

@@ -0,0 +1,36 @@
+import type { Constructable } from "../reflection/index.js";
+import type { UnionToIntersection } from "../system/type.utils.js";
+export declare const ActionMap: unique symbol;
+export type ActionClassMap = Record<string, Constructable<Action>>;
+export interface ResultStatus {
+    succeeded: boolean;
+    error?: string;
+}
+export interface Result {
+    readonly name: string;
+    readonly succeeded: boolean;
+    readonly skipped: boolean;
+    readonly message: string;
+}
+export declare class ActionResponse<TData = unknown> implements Result {
+    static Success<TData>(name: string, data?: TData[]): ActionResponse<TData>;
+    static Skipped(name: string): ActionResponse<unknown>;
+    static Blocking(name: string): ActionResponse<unknown>;
+    static Error<TData = unknown>(name: string, message: string): ActionResponse<TData>;
+    static Error<TData extends ResultStatus>(name: string, data: TData[]): ActionResponse<TData>;
+    constructor(data: Partial<ActionResponse<TData>>);
+    readonly name: string;
+    readonly succeeded: boolean;
+    readonly skipped: boolean;
+    readonly blocking: boolean;
+    readonly message: string;
+    readonly data: TData[];
+}
+export interface Action<T extends object = object> {
+    run(options: T): Promise<ActionResponse>;
+}
+export type Actions = Record<string, Action>;
+export type ActionOptions<A extends Action> = A extends Action<infer T> ? T : never;
+export type MergeOptions<TActions extends Record<string, Action>> = UnionToIntersection<{
+    [K in keyof TActions]: ActionOptions<TActions[K]>;
+}[keyof TActions]>;

package/types/src/cli/command.d.ts

@@ -0,0 +1,34 @@
+import { Command as CommanderType, type OptionValues } from "commander";
+import type { Constructable } from "../reflection/index.js";
+import type { ActionResponse, Actions } from "./action.js";
+export type CommandType = Constructable<DecohereCommand>;
+export type CommandHandler = (opts: OptionValues, cmd: DecohereCommand) => Promise<void>;
+export type CommandResponse<TActions extends Actions = Actions> = {
+    [ActionName in keyof TActions]?: ActionResponse;
+};
+export declare const CommandResponse: {
+    success<T extends Actions>(_ctx: unknown, responses: CommandResponse<T>): CommandResponse<T>;
+    help<T extends Actions = Actions>(): CommandResponse<T>;
+    fromAction(name: string, response: ActionResponse): CommandResponse;
+};
+/** Thrown when a command execution fails due to action errors. */
+export declare class CommandError extends Error {
+}
+export declare class DecohereCommand<TActions extends Actions = Actions> extends CommanderType {
+    get actions(): readonly Constructable<import("./action.js").Action>[];
+    constructor(name?: string | Constructable | Record<string, CommandType>, handler?: CommandHandler);
+    /**
+     * Whether the command, with these options, runs until it is stopped (`flux serve`,
+     * `forge build --watch`). The CLI then listens for SIGINT and SIGTERM from the moment it
+     * starts, so a stop during start-up still shuts down cleanly; other commands keep Node's
+     * default, where Ctrl+C ends them at once.
+     */
+    runsUntilStopped(_options: OptionValues): boolean;
+    run(actions: TActions, options: OptionValues): Promise<CommandResponse<TActions>>;
+    registerSubcommand(command: CommandType, onAction?: CommandHandler): void;
+    registerSubcommand(commands: Record<string, DecohereCommand | CommandType>, onAction?: CommandHandler): void;
+    protected runActions(actions: TActions, options: OptionValues): Promise<CommandResponse<TActions>>;
+    protected getSelectedActions(actions: TActions): Array<[keyof TActions, TActions[keyof TActions]]>;
+    protected throwOnErrors(responses: CommandResponse<TActions>): void;
+    private parseCommandName;
+}