@decohere/core 0.0.1-dev.116

package/types/src/objects/deep-merge.d.ts

@@ -0,0 +1,41 @@
+type TAllKeys<T> = T extends unknown ? keyof T : never;
+type TIndexValue<T, K extends PropertyKey, D = never> = T extends unknown ? K extends keyof T ? T[K] : D : never;
+type TPartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>> extends infer O ? {
+    [P in keyof O]: O[P];
+} : never;
+type TFunction = (...a: unknown[]) => unknown;
+type TPrimitives = string | number | boolean | bigint | symbol | Date | TFunction;
+type TMerged<T> = [T] extends [Array<unknown>] ? {
+    [K in keyof T]: TMerged<T[K]>;
+} : [T] extends [TPrimitives] ? T : [T] extends [object] ? TPartialKeys<{
+    [K in TAllKeys<T>]: TMerged<TIndexValue<T, K>>;
+}, never> : T;
+export declare const merge: {
+    <T extends object[]>(...objects: T): TMerged<T[number]>;
+    options: IOptions;
+    withOptions<R = unknown, T extends object[] = object[]>(options: Partial<IOptions>, ...objects: T): R;
+};
+interface IOptions {
+    /**
+     * When `true`, values explicitly provided as `undefined` will override existing values, though properties that are simply omitted won't affect anything.
+     * When `false`, values explicitly provided as `undefined` won't override existing values.
+     *
+     * Default: `true`
+     */
+    allowUndefinedOverrides: boolean;
+    /**
+     * When `true` it will merge array properties.
+     * When `false` it will replace array properties with the last instance entirely instead of merging their contents.
+     *
+     * Default: `true`
+     */
+    mergeArrays: boolean;
+    /**
+     * When `true` it will ensure there are no duplicate array items.
+     * When `false` it will allow duplicates when merging arrays.
+     *
+     * Default: `true`
+     */
+    uniqueArrayItems: boolean;
+}
+export {};

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

@@ -0,0 +1 @@
+export { merge } from "./deep-merge.js";

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

@@ -0,0 +1,3 @@
+import "reflect-metadata";
+export * from "./types/index.js";
+export * from "./utilities.js";

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

@@ -0,0 +1 @@
+export * from "./reflection.types.js";

package/types/src/reflection/types/reflection.types.d.ts

@@ -0,0 +1,21 @@
+export type Constructable<T extends object = object> = {
+    new (...args: any[]): T;
+} & Type;
+export type Field = {
+    key: string;
+    propertyDescriptor: PropertyDescriptor;
+};
+export type FunctionType = (...args: unknown[]) => unknown | unknown[] | undefined | Promise<unknown>;
+export type ReflectMeta = "paramtypes" | "type";
+export declare const MetaDataOwners: {
+    Hearth: string;
+    Reflect: string;
+};
+export declare const ReflectionMeta: {
+    paramtypes: string;
+    type: string;
+};
+export type Type = {
+    prototype: object;
+    name?: string;
+};

package/types/src/reflection/utilities.d.ts

@@ -0,0 +1,27 @@
+import { type Constructable, type Field, type FunctionType, type Type } from "./types/reflection.types.js";
+export declare const isPrimitiveOrDateType: (type: Type) => boolean;
+export declare const isDateType: (type: Type) => boolean;
+export declare function isConstructable(type: Constructable | object | FunctionType): type is Constructable;
+export declare const isArrayType: (type: Type) => boolean;
+export declare function getMeta<T>(key: string, target: object, propertyKey?: string): T;
+export declare function getFunctions(object: Constructable): PropertyDescriptor[];
+export declare function getFunction(object: Constructable, functionName: string): PropertyDescriptor;
+export declare function getFunctionMetadata<T>(key: string, target: object, func: FunctionType): T;
+export declare function getFunctionArgs(target: object, func: FunctionType): Type[];
+/**
+ * @description Gets the fields from an object
+ * @param object
+ * @returns
+ */
+export declare function getFields<T>(object: T): Field[];
+export declare function getFieldType(target: object, fieldName: string): Type;
+export declare function getArgumentMeta<T>(key: string, target: FunctionType, argIndex: number): T;
+export declare function defineMeta<T>(key: string, value: T, target: object): void;
+/**
+ * @description Facade function to define metadata for a function argument
+ * @param key
+ * @param value
+ * @param func
+ * @param argIndex
+ */
+export declare function defineArgumentMeta<T>(key: string, value: T, func: FunctionType, argIndex: number): void;

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

@@ -0,0 +1 @@
+export * from "./semver.js";

package/types/src/semver/semver.d.ts

@@ -0,0 +1,18 @@
+export type VersionType = "major" | "minor" | "patch" | "prerelease";
+export declare const VersionTypes: {
+    major: "major";
+    minor: "minor";
+    patch: "patch";
+    prerelease: "prerelease";
+};
+export declare class SemverError extends Error {
+    constructor(message: string);
+}
+export declare class Semver {
+    private version;
+    constructor(version: string);
+    increment(versionType: VersionType, preid?: string): Semver;
+    toString(): string;
+    private ensureValid;
+    private parse;
+}

package/types/src/system/camel-case.d.ts

@@ -0,0 +1 @@
+export declare function lowerCamelCase(val: any): string;

package/types/src/system/debounce.d.ts

@@ -0,0 +1 @@
+export declare function debounce<T extends unknown[]>(callback: (...args: T) => Promise<void>, delay: number): (...args: T) => void;

package/types/src/system/decorator.d.ts

@@ -0,0 +1,15 @@
+export declare abstract class FunctionDecorator<TOptions = undefined> {
+    protected options: TOptions;
+    constructor();
+    abstract decorator(target: object, propertyKey: string, descriptor: PropertyDescriptor): any;
+    decoratorFactory(options?: TOptions): any;
+}
+/**
+ * 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 declare function ignoreIf(...envVars: string[]): (_: object, __: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/** @deprecated Use ignoreIf("TEST") instead */
+export declare function ignoreDuringUnitTest(): (_: object, __: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/types/src/system/environment.d.ts

@@ -0,0 +1,6 @@
+export type Environment = "production" | "development";
+export declare const Environments: {
+    production: "production";
+    development: "development";
+};
+export declare const DefaultEnvironment: "development";

package/types/src/system/function.types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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>>;
+ * ```
+ */
+export type Func<TArgs extends readonly unknown[] = [], TReturn = void> = (...args: TArgs) => TReturn;
+/**
+ * Async function type that returns a Promise.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: (id: string) => Promise<User>
+ * type GetUser = AsyncFunc<[string], User>;
+ *
+ * // Instead of: () => Promise<void>
+ * type InitFunc = AsyncFunc<[], void>;
+ * ```
+ */
+export type AsyncFunc<TArgs extends readonly unknown[] = [], TReturn = void> = Func<TArgs, Promise<TReturn>>;
+/**
+ * Predicate function type that returns a boolean.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: (item: T) => boolean
+ * type Filter<T> = Predicate<[T]>;
+ *
+ * // Instead of: (a: number, b: number) => boolean
+ * type Comparator = Predicate<[number, number]>;
+ * ```
+ */
+export type Predicate<TArgs extends readonly unknown[] = []> = Func<TArgs, boolean>;
+/**
+ * Action function type that returns void.
+ *
+ * @example
+ * ```typescript
+ * // Instead of: (event: Event) => void
+ * type EventHandler = Action<[Event]>;
+ *
+ * // Instead of: () => void
+ * type Callback = Action<[]>;
+ * ```
+ */
+export type Action<TArgs extends readonly unknown[] = []> = Func<TArgs, void>;

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

@@ -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/types/src/system/retry.decorator.d.ts

@@ -0,0 +1,6 @@
+export type RetryOptions = {
+    attempts?: number;
+    delayMs?: number;
+    shouldRetry?: (error: unknown) => boolean;
+};
+export declare const retry: (options?: RetryOptions) => any;

package/types/src/system/sleep.d.ts

@@ -0,0 +1 @@
+export declare const sleep: (ms: number) => Promise<unknown>;

package/types/src/system/type.utils.d.ts

@@ -0,0 +1 @@
+export type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;

package/types/src/testing/flush-promises.d.ts

@@ -0,0 +1 @@
+export declare function flushPromises(): Promise<unknown>;

package/types/src/testing/glob-with-memfs.d.ts

@@ -0,0 +1,3 @@
+export declare function withMemfsFsForGlob<TGlobModule extends {
+    glob: (...args: unknown[]) => unknown;
+}>(actual: TGlobModule): TGlobModule;

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

@@ -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/types/src/testing/memfs.d.ts

@@ -0,0 +1,5 @@
+export declare function resetMemfs(): void;
+export declare function seedMemfs(files: Record<string, string>): void;
+export declare function createTestFile(filePath: string, content: string | Buffer): void;
+export declare function readFile(filePath: string): Promise<string>;
+export declare function fileExists(filePath: string): boolean;

package/types/src/testing/mock-logger.d.ts

@@ -0,0 +1,13 @@
+export type LoggerMethod = (msg: string | number | object, ...args: unknown[]) => void;
+export type TestLogger = {
+    fatal: LoggerMethod;
+    error: LoggerMethod;
+    warn: LoggerMethod;
+    info: LoggerMethod;
+    debug: LoggerMethod;
+    trace: LoggerMethod;
+    isLevelEnabled(level: string): boolean;
+    readonly currentLevel: string;
+    readonly logLevels: Record<string, number>;
+};
+export declare function createMockLogger(): TestLogger;

package/types/src/testing/spy-on-constructor.d.ts

@@ -0,0 +1,21 @@
+import { vi } from "vitest";
+import type { Constructable } from "../reflection/index.js";
+/**
+ * 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 declare function spyOnConstructor<T extends Constructable>(Target: T): {
+    spy: ReturnType<typeof vi.fn>;
+    Proxy: T;
+};