@mxweb/classable 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-01-17
+
+### Added
+
+- **Type Utilities**
+  - `Readonlyable<T>` - Utility type that accepts both mutable and readonly versions, useful for `Object.freeze()` or `as const`
+  - `InstanceByStatic<T, Method, Args, Runtime>` - Type for classes using static factory methods instead of direct constructor instantiation
+  - `ClassableSelector<T, Args, Runtime>` - Selector function type for choosing a classable from a list with custom logic
+
+- **classable API**
+  - `classable.from(def, runtime?)` - Create an instance via a static factory method definition
+  - `classable.select(selector)` - Higher-order function to create a selector that picks a classable based on custom criteria
+  - `classable.placeholderInstance` - Pre-configured placeholder using InstanceByStatic pattern
+
+- **Placeholder**
+  - Added `Placeholder.getInstance()` static method for factory pattern support
+
+### Changed
+
+- Updated `Args` type parameter across all APIs to use `Readonlyable<any[]>` for flexible readonly/mutable array support
+- `ClassableByResolver.target` now uses `[...Args]` spread to convert readonly arrays to mutable
+- `Classable` type now properly handles readonly arrays
+- `StaticExtended` type updated to support `Readonlyable<any[]>`
+
 ## [1.0.0] - 2026-01-17
 
 ### Added
@@ -41,4 +65,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Comprehensive README with examples
   - MIT License
 
+[1.1.0]: https://github.com/mxwebio/mxweb-classable/releases/tag/v1.1.0
 [1.0.0]: https://github.com/mxwebio/mxweb-classable/releases/tag/v1.0.0

package/README.md

@@ -85,12 +85,30 @@ interface ClassableByResolver<InstanceType, Args, Runtime> {
 }
 ```
 
+### Readonlyable
+
+All `Args` type parameters accept both mutable and readonly arrays, so you can use `Object.freeze()` or `as const` without type errors:
+
+```typescript
+// Both work seamlessly
+const mutableResolver = {
+  target: User,
+  resolve: () => ['John', 30]  // mutable array
+};
+
+const frozenResolver = Object.freeze({
+  target: User,
+  resolve: () => ['John', 30] as const  // readonly array
+});
+```
+
 ## API Reference
 
 ### Type Utilities
 
 | Type | Description |
 |------|-------------|
+| `Readonlyable<T>` | Accepts both mutable and readonly versions of a type |
 | `UnitClass<T>` | Class constructor with no arguments |
 | `ClassType<T, Args>` | Class constructor with specific arguments |
 | `AbstractClassType<T, Args>` | Abstract class constructor |
@@ -99,6 +117,8 @@ interface ClassableByResolver<InstanceType, Args, Runtime> {
 | `AnyConstructor` | Any class or abstract class |
 | `Classable<T, Args, Runtime>` | Class or resolver configuration |
 | `ClassableByResolver<T, Args, Runtime>` | Resolver configuration |
+| `InstanceByStatic<T, Method, Args, Runtime>` | Static factory method pattern |
+| `ClassableSelector<T, Args, Runtime>` | Selector function for choosing classables |
 
 ### `classable` API
 
@@ -211,14 +231,57 @@ classable.getDescriptor(resolver);
 // { type: "resolver", target: "User" }
 ```
 
+#### `classable.from(def, runtime?)`
+
+Creates an instance from a static factory method definition.
+
+```typescript
+class Cache {
+  private constructor(private ttl: number) {}
+  
+  static create(ttl: number): Cache {
+    return new Cache(ttl);
+  }
+}
+
+const cacheInstance = classable.from({
+  target: Cache,
+  selector: () => ({ method: "create", args: [3600] })
+});
+
+// With runtime context
+const dynamicCache = classable.from({
+  target: Cache,
+  selector: (ctx) => ({ method: "create", args: [ctx.cacheTTL] })
+}, appContext);
+```
+
+#### `classable.select(selector)`
+
+Creates a selector function that chooses a classable from a list based on custom logic.
+
+```typescript
+// Simple selector
+const pickFirst = classable.select((...classes) => {
+  return [classes[0], []];
+});
+const [selected, args] = pickFirst(ServiceA, ServiceB);
+
+// With runtime context
+const pickByEnv = classable.select<Logger, [], Env>((env, ...loggers) => {
+  return env.isDev ? [loggers[0], []] : [loggers[1], []];
+});
+const [logger, loggerArgs] = pickByEnv(devEnv, DevLogger, ProdLogger);
+```
+
 ### Placeholder
 
-A utility class for marking unresolved bindings:
+Utility classes for marking unresolved bindings:
 
 ```typescript
 import { classable } from '@mxweb/classable';
 
-// Use as default value
+// Use placeholder resolver as default value
 class Container {
   private bindings = new Map();
   
@@ -226,10 +289,51 @@ class Container {
     this.bindings.set(key, cls);
   }
 }
+
+// Use placeholderInstance for static factory pattern
+const instance = classable.from(classable.placeholderInstance);
+// Returns new Placeholder via getInstance()
 ```
 
 ## Advanced Usage
 
+### Static Factory Method Pattern
+
+Use `InstanceByStatic` for classes that use static factory methods instead of direct instantiation:
+
+```typescript
+import { classable, InstanceByStatic } from '@mxweb/classable';
+
+class Database {
+  private constructor(private connectionString: string) {}
+  
+  static connect(connectionString: string): Database {
+    return new Database(connectionString);
+  }
+  
+  static createInMemory(): Database {
+    return new Database(':memory:');
+  }
+}
+
+// Define static factory configuration
+const dbDef: InstanceByStatic<Database, 'connect', [string]> = {
+  target: Database,
+  selector: () => ({ method: 'connect', args: ['postgres://localhost'] })
+};
+
+// Create instance via factory method
+const db = classable.from(dbDef);
+
+// With runtime context for dynamic selection
+const dynamicDb = classable.from({
+  target: Database,
+  selector: (ctx) => ctx.isTest
+    ? { method: 'createInMemory', args: [] }
+    : { method: 'connect', args: [ctx.dbUrl] }
+}, appContext);
+```
+
 ### Dependency Injection Pattern
 
 ```typescript
@@ -332,6 +436,12 @@ const asyncResolver = {
 const asyncUser = classable.create(asyncResolver, context); // Promise<User>
 ```
 
+## Documentation
+
+For detailed documentation, guides, and API reference, visit:
+
+[https://edge.mxweb.io/classable](https://edge.mxweb.io/classable)
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Utility type that accepts both mutable and readonly versions of a type.
+ *
+ * This is useful for accepting values from `Object.freeze()` or `as const`
+ * without forcing users to always use readonly modifiers.
+ *
+ * @template T - The base type to make flexible.
+ *
+ * @example
+ * ```typescript
+ * // Accepts both mutable and readonly arrays
+ * function process(items: Readonlyable<string[]>) { ... }
+ *
+ * process(["a", "b"]);           // mutable array - OK
+ * process(["a", "b"] as const);  // readonly array - OK
+ * ```
+ */
+export type Readonlyable<T> = T extends Readonly<infer U> ? U | Readonly<U> : T | Readonly<T>;
 /**
  * Represents a class constructor that takes no arguments.
  * @template InstanceType - The type of instance created by this constructor.
@@ -79,9 +97,9 @@ export type AnyConstructor = ClassType<any, any[]> | AbstractClassType<any, any[
  * };
  * ```
  */
-export interface ClassableByResolver<InstanceType, Args extends any[] = [], Runtime = never> {
+export interface ClassableByResolver<InstanceType, Args extends Readonlyable<any[]> = [], Runtime = never> {
     /** The target class constructor to instantiate. */
-    target: ClassType<InstanceType, Args>;
+    target: ClassType<InstanceType, [...Args]>;
     /**
      * Function that resolves constructor arguments.
      * Can return arguments synchronously or as a Promise.
@@ -107,7 +125,7 @@ export interface ClassableByResolver<InstanceType, Args extends any[] = [], Runt
  * register({ target: User, resolve: () => ["John", 30] });
  * ```
  */
-export type Classable<InstanceType, Args extends any[] = [], Runtime = never> = ClassType<InstanceType, Args> | ClassableByResolver<InstanceType, Args, Runtime>;
+export type Classable<InstanceType, Args extends Readonlyable<any[]> = [], Runtime = never> = ClassType<InstanceType, [...Args]> | ClassableByResolver<InstanceType, Args, Runtime>;
 /**
  * A placeholder class used as a marker for unresolved or pending class registrations.
  * Useful in dependency injection containers or lazy initialization patterns.
@@ -124,6 +142,7 @@ export type Classable<InstanceType, Args extends any[] = [], Runtime = never> =
  * ```
  */
 export declare class Placeholder {
+    static getInstance(): Placeholder;
 }
 /**
  * Pre-configured placeholder resolver that creates an empty Placeholder instance.
@@ -147,7 +166,91 @@ export type ThisExtended<Extend> = Placeholder & Extend;
  * @template InstanceType - The instance type of the class.
  * @template Args - Constructor argument types.
  */
-export type StaticExtended<Extend, InstanceType = any, Args extends any[] = []> = ClassType<InstanceType, Args> & Extend;
+export type StaticExtended<Extend, InstanceType = any, Args extends Readonlyable<any[]> = []> = ClassType<InstanceType, [...Args]> & Extend;
+/**
+ * Represents a class whose instances are created via a static factory method.
+ *
+ * This type is used for classes that expose a static method (e.g., `factory`, `create`)
+ * for instantiation instead of using `new` directly.
+ *
+ * @template InstanceType - The type of instance created by the static method.
+ * @template Method - The name of the static method to call (defaults to "factory").
+ * @template Args - Tuple type of arguments passed to the static method.
+ * @template Runtime - Optional runtime context type passed to the selector.
+ *
+ * @remarks
+ * - The constructor MAY exist and MAY take arguments.
+ * - Constructor arguments are considered an implementation detail
+ *   and are intentionally typed as `any[]`.
+ * - Consumers MUST NOT rely on `new`.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   private constructor(private db: Database) {}
+ *
+ *   static factory(db: Database): UserService {
+ *     return new UserService(db);
+ *   }
+ * }
+ *
+ * const def: InstanceByStatic<UserService, "factory", [Database]> = {
+ *   target: UserService,
+ *   selector: () => ({ method: "factory", args: [new Database()] })
+ * };
+ * ```
+ */
+export type InstanceByStatic<InstanceType, Method extends string = "factory", Args extends Readonlyable<any[]> = [], Runtime = never> = {
+    target: StaticExtended<{
+        [K in Method]: (...args: Args) => InstanceType;
+    }, InstanceType, any[]>;
+    selector: (...args: Runtime extends never ? [] : [runtime: Runtime]) => {
+        method: Method;
+        args: Args;
+    };
+};
+/**
+ * Pre-configured placeholder instance using static factory method pattern.
+ * Use this as a default value for InstanceByStatic bindings.
+ *
+ * @example
+ * ```typescript
+ * const instance = classable.from(classable.placeholderInstance);
+ * // Returns new Placeholder instance via getInstance()
+ * ```
+ */
+export declare const placeholderInstance: Readonly<{
+    target: typeof Placeholder;
+    selector: () => {
+        method: string;
+        args: [];
+    };
+}>;
+/**
+ * A selector function that chooses and returns a classable with its arguments.
+ *
+ * This type represents a function that takes a list of classables (and optionally a runtime context)
+ * and returns the selected classable along with its constructor arguments.
+ *
+ * @template InstanceType - The type of instance to be created.
+ * @template Args - Tuple type of constructor arguments.
+ * @template Runtime - Optional runtime context type for dependency resolution.
+ *
+ * @returns A tuple of [Classable, Args] or a Promise resolving to the same.
+ *
+ * @example
+ * ```typescript
+ * const selectByEnv: ClassableSelector<Logger, [], AppContext> = (runtime, ...classes) => {
+ *   const LoggerClass = runtime.isDev ? DevLogger : ProdLogger;
+ *   return [LoggerClass, []];
+ * };
+ *
+ * const selectFirst: ClassableSelector<Service, [string]> = (...classes) => {
+ *   return [classes[0] as Classable<Service, [string]>, ["default"]];
+ * };
+ * ```
+ */
+export type ClassableSelector<InstanceType, Args extends Readonlyable<any[]> = [], Runtime = never> = (...args: Runtime extends never ? Array<Classable<any, any[]>> : [runtime: Runtime, ...Array<Classable<any, any[], Runtime>>]) => [Classable<InstanceType, Args>, Args] | Promise<[Classable<InstanceType, Args>, Args]>;
 /**
  * Interface defining all available methods on the `classable` API object.
  * This provides type-safe access to class manipulation utilities.
@@ -156,19 +259,21 @@ export interface ClassableAPI {
     /** Reference to the Placeholder class constructor. */
     Placeholder: ClassType<Placeholder>;
     /** Pre-configured placeholder resolver instance. */
-    placeholder: ClassableByResolver<Placeholder>;
+    placeholder: ClassableByResolver<Placeholder, readonly []>;
+    /** Pre-configured placeholder instance using InstanceByStatic pattern. */
+    placeholderInstance: InstanceByStatic<Placeholder, "getInstance", []>;
     /** Checks if a value is a class constructor. */
     is: (fn: unknown) => fn is AnyClass<any>;
     /** Checks if a value is an abstract class constructor. */
     isAbstract: (fn: unknown) => fn is AnyAbstractClass<any>;
     /** Checks if a value is a ClassableByResolver object. */
-    isResolver: <InstanceType, Args extends any[] = [], Runtime = never>(obj: unknown) => obj is ClassableByResolver<InstanceType, Args, Runtime>;
+    isResolver: <InstanceType, Args extends Readonlyable<any[]> = [], Runtime = never>(obj: unknown) => obj is ClassableByResolver<InstanceType, Args, Runtime>;
     /** Converts a class constructor to a resolver configuration. */
-    toResolver<T, A extends any[] = [], R = never>(cls: ClassType<T, A>, runtime?: R): ClassableByResolver<T, [], R>;
+    toResolver<T, A extends Readonlyable<any[]> = [], R = never>(cls: ClassType<T, [...A]>, runtime?: R): ClassableByResolver<T, [], R>;
     /** Extracts the target class from a Classable (class or resolver). */
     getTarget: <Target>(cls: Classable<Target, any[], any>) => Target;
     /** Creates a new resolver with a custom resolve function. */
-    withResolve: <InstanceType, Args extends any[] = [], Runtime = never>(base: Classable<InstanceType, Args, Runtime>, resolve: ClassableByResolver<InstanceType, Args, Runtime>["resolve"]) => ClassableByResolver<InstanceType, Args, Runtime>;
+    withResolve: <InstanceType, Args extends Readonlyable<any[]> = [], Runtime = never>(base: Classable<InstanceType, Args, Runtime>, resolve: ClassableByResolver<InstanceType, Args, Runtime>["resolve"]) => ClassableByResolver<InstanceType, Args, Runtime>;
     /** Wraps a class with a transformation function. */
     wrap<T>(cls: ClassType<T>, wrapper: (target: ClassType<T>) => ClassType<T>): ClassType<T>;
     /** Wraps a resolver's target with a transformation function. */
@@ -181,13 +286,64 @@ export interface ClassableAPI {
     /** Creates an instance from a plain class. */
     create<InstanceType>(cls: ClassType<InstanceType>): InstanceType;
     /** Creates an instance from a resolver with sync resolve function. */
-    create<InstanceType, Args extends any[], Runtime>(cls: ClassableByResolver<InstanceType, Args, Runtime> & {
+    create<InstanceType, Args extends Readonlyable<any[]>, Runtime>(cls: ClassableByResolver<InstanceType, Args, Runtime> & {
         resolve: (runtime: Runtime) => Args;
     }, runtime: Runtime): InstanceType;
     /** Creates an instance from a resolver with async resolve function. */
-    create<InstanceType, Args extends any[], Runtime>(cls: ClassableByResolver<InstanceType, Args, Runtime> & {
+    create<InstanceType, Args extends Readonlyable<any[]>, Runtime>(cls: ClassableByResolver<InstanceType, Args, Runtime> & {
         resolve: (runtime: Runtime) => Promise<Args>;
     }, runtime: Runtime): Promise<InstanceType>;
+    /**
+     * Creates an instance from a static factory method definition.
+     *
+     * This method invokes the static method specified in the `InstanceByStatic` definition
+     * to create an instance, allowing for factory pattern implementations.
+     *
+     * @template InstanceType - The type of instance created.
+     * @template Method - The static method name to invoke.
+     * @template Args - Arguments passed to the static method.
+     * @template Runtime - Optional runtime context type.
+     * @param def - The static factory definition containing target class and selector.
+     * @param runtime - Optional runtime context passed to the selector.
+     * @returns The created instance.
+     *
+     * @example
+     * ```typescript
+     * class Cache {
+     *   static create(ttl: number): Cache { return new Cache(ttl); }
+     * }
+     *
+     * const instance = classable.from({
+     *   target: Cache,
+     *   selector: () => ({ method: "create", args: [3600] })
+     * });
+     * ```
+     */
+    from: <InstanceType, Method extends string = "factory", Args extends Readonlyable<any[]> = [], Runtime = never>(def: InstanceByStatic<InstanceType, Method, Args, Runtime>, runtime?: Runtime) => InstanceType;
+    /**
+     * Creates a selector function that chooses a classable from a list based on custom logic.
+     *
+     * This higher-order function takes a selection strategy and returns a function
+     * that can be called with classables to select and instantiate the appropriate one.
+     *
+     * @template InstanceType - The type of instance to be created.
+     * @template Args - Constructor arguments for the selected classable.
+     * @template Runtime - Optional runtime context type.
+     * @param select - The selector function that implements the selection logic.
+     * @returns A function that accepts classables and returns the selection result.
+     *
+     * @example
+     * ```typescript
+     * const pickFirst = classable.select((cls1, cls2) => [cls1, []]);
+     * const [selected, args] = pickFirst(ServiceA, ServiceB);
+     *
+     * // With runtime context
+     * const pickByEnv = classable.select<Logger, [], Env>((env, ...loggers) => {
+     *   return env.isDev ? [loggers[0], []] : [loggers[1], []];
+     * });
+     * ```
+     */
+    select: <InstanceType, Args extends Readonlyable<any[]> = [], Runtime = never>(select: ClassableSelector<InstanceType, Args, Runtime>) => (...args: Runtime extends never ? [...classes: Array<Classable<any, any[], Runtime>>] : [runtime: Runtime, ...classes: Array<Classable<any, any[], Runtime>>]) => ReturnType<ClassableSelector<InstanceType, Args, Runtime>>;
 }
 /**
  * The main classable API object providing utilities for working with classes and resolvers.

package/dist/index.mjs

@@ -1 +1 @@
-function e(e,t){return"object"==typeof e&&null!==e&&Object.prototype.hasOwnProperty.call(e,t)}class t{}const r=Object.freeze({target:t,resolve:()=>[]}),o=Object.freeze({Placeholder:t,placeholder:r,is:e=>"function"==typeof e&&/^class\s/.test(Function.prototype.toString.call(e)),isAbstract:e=>"function"==typeof e&&/^abstract\s+class\s/.test(Function.prototype.toString.call(e)),isResolver:t=>e(t,"target")&&o.is(t.target)&&e(t,"resolve")&&"function"==typeof t.resolve,toResolver:e=>o.isResolver(e)?e:{target:e,resolve:()=>[]},create:(e,t)=>{if(o.isResolver(e)){const r=e.resolve(...void 0===t?[]:[t]);return r instanceof Promise?r.then(t=>new e.target(...t)):new e.target(...r)}return new e(...[])},getTarget:e=>o.isResolver(e)?e.target:e,withResolve:(e,t)=>({target:(o.isResolver(e)?e:o.toResolver(e)).target,resolve:t}),wrap:(e,t)=>o.isResolver(e)?{target:t(e.target),resolve:e.resolve}:t(e),getDescriptor:e=>o.isResolver(e)?{type:"resolver",target:e.target.name}:{type:"class",target:e.name}});export{t as Placeholder,o as classable,r as placeholder};
+function e(e,t){return"object"==typeof e&&null!==e&&Object.prototype.hasOwnProperty.call(e,t)}class t{static getInstance(){return new t}}const r=Object.freeze({target:t,resolve:()=>[]}),s=Object.freeze({target:t,selector:()=>({method:"getInstance",args:[]})}),o=Object.freeze({Placeholder:t,placeholder:r,placeholderInstance:s,is:e=>"function"==typeof e&&/^class\s/.test(Function.prototype.toString.call(e)),isAbstract:e=>"function"==typeof e&&/^abstract\s+class\s/.test(Function.prototype.toString.call(e)),isResolver:t=>e(t,"target")&&o.is(t.target)&&e(t,"resolve")&&"function"==typeof t.resolve,toResolver:e=>o.isResolver(e)?e:{target:e,resolve:()=>[]},create:(e,t)=>{if(o.isResolver(e)){const r=e.resolve(...void 0===t?[]:[t]);return r instanceof Promise?r.then(t=>new e.target(...t)):new e.target(...r)}return new e(...[])},getTarget:e=>o.isResolver(e)?e.target:e,withResolve:(e,t)=>({target:(o.isResolver(e)?e:o.toResolver(e)).target,resolve:t}),wrap:(e,t)=>o.isResolver(e)?{target:t(e.target),resolve:e.resolve}:t(e),getDescriptor:e=>o.isResolver(e)?{type:"resolver",target:e.target.name}:{type:"class",target:e.name},from:(e,t)=>{const{target:r,selector:s}=e,{method:o,args:a}=s(...void 0===t?[]:[t]);return r[o](...a)},select:e=>(...t)=>e(...t)});export{t as Placeholder,o as classable,r as placeholder,s as placeholderInstance};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxweb/classable",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A class-first abstraction for defining logic as resolvable units without runtime assumptions.",
   "license": "MIT",
   "keywords": [
@@ -11,7 +11,9 @@
     "resolver",
     "meta-programming",
     "framework-agnostic",
-    "esm-only"
+    "esm-only",
+    "static-factory",
+    "dependency-injection"
   ],
   "type": "module",
   "module": "dist/index.js",
@@ -38,7 +40,8 @@
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\""
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\"",
+    "prepublishOnly": "yarn build"
   },
   "devDependencies": {
     "@babel/core": "^7.28.6",