katagami 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hiroiku
+
+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,193 @@
+# Katagami
+
+Lightweight TypeScript DI container with full type inference.
+
+## Why Katagami
+
+Most TypeScript DI containers rely on decorators, reflect-metadata, or string-based tokens — each bringing trade-offs in tooling compatibility, type safety, or bundle size. Katagami takes a different approach.
+
+### No decorators, no reflect-metadata
+
+Decorator-based DI requires `experimentalDecorators` and `emitDecoratorMetadata` compiler options. Modern build tools such as esbuild, Vite, and SWC do not support `emitDecoratorMetadata`, and the TC39 standard decorators proposal does not include it either. Katagami depends on none of these — it works with any build tool out of the box.
+
+### Full type inference from class tokens
+
+String-token DI forces you to maintain manual token-to-type mappings. Parameter-name matching breaks under minification. Katagami uses classes directly as tokens, so `resolve` automatically infers the correct return type — synchronous or `Promise` — with no extra annotations.
+
+### Method-chain type accumulation
+
+Types accumulate with each `register` call. Inside a factory, the resolver only accepts tokens that have already been registered at that point in the chain. Resolving an unregistered token is a compile-time error, not a runtime surprise.
+
+### Hybrid token strategy
+
+Class tokens give you strict, order-dependent type safety through method chaining. But sometimes you want to define a set of services upfront and register them in any order. Pass an interface to `createContainer<T>()` and use PropertyKey tokens — the type map is fixed at creation time, so registration order does not matter.
+
+### Zero dependencies
+
+No runtime dependencies, no polyfills. No need to add reflect-metadata (20–50 KB) to your bundle.
+
+## Install
+
+```bash
+npm install katagami
+```
+
+## Usage (TypeScript)
+
+Use class tokens for full type inference:
+
+```ts
+import { createContainer } from 'katagami';
+
+class Logger {
+	log(msg: string) {
+		console.log(msg);
+	}
+}
+
+class UserService {
+	constructor(private logger: Logger) {}
+	greet(name: string) {
+		this.logger.log(`Hello, ${name}`);
+	}
+}
+
+const container = createContainer()
+	.registerSingleton(Logger, () => new Logger())
+	.registerSingleton(UserService, r => new UserService(r.resolve(Logger)));
+
+const userService = container.resolve(UserService);
+//    ^? UserService (fully inferred)
+userService.greet('world');
+```
+
+## Usage (JavaScript)
+
+Use string or Symbol tokens:
+
+```js
+import { createContainer } from 'katagami';
+
+const container = createContainer()
+	.registerSingleton('logger', () => ({
+		log: msg => console.log(msg),
+	}))
+	.registerSingleton('userService', r => ({
+		greet: name => r.resolve('logger').log(`Hello, ${name}`),
+	}));
+
+const userService = container.resolve('userService');
+userService.greet('world');
+```
+
+## Async Factories
+
+Factories that return a `Promise` are automatically tracked by the type system. When you `resolve` an async token, the return type is `Promise<V>` instead of `V`:
+
+```ts
+import { createContainer } from 'katagami';
+
+class Database {
+	constructor(public connected: boolean) {}
+}
+
+class Logger {
+	log(msg: string) {
+		console.log(msg);
+	}
+}
+
+const container = createContainer()
+	.registerSingleton(Logger, () => new Logger())
+	.registerSingleton(Database, async () => {
+		await new Promise(r => setTimeout(r, 100)); // simulate async init
+		return new Database(true);
+	});
+
+const logger = container.resolve(Logger);
+//    ^? Logger
+
+const db = await container.resolve(Database);
+//    ^? Promise<Database>  (awaited → Database)
+db.connected; // true
+```
+
+Async factories can depend on both sync and async registrations:
+
+```ts
+const container = createContainer()
+	.registerSingleton(Logger, () => new Logger())
+	.registerSingleton(Database, async r => {
+		const logger = r.resolve(Logger); // sync → Logger
+		logger.log('Connecting...');
+		return new Database(true);
+	});
+```
+
+## Interface Type Map
+
+When you pass an interface to `createContainer<T>()`, PropertyKey tokens are typed from the interface rather than accumulated through chaining. This means you can register and resolve tokens in any order:
+
+```ts
+import { createContainer } from 'katagami';
+
+class Logger {
+	log(msg: string) {
+		console.log(msg);
+	}
+}
+
+interface Services {
+	logger: Logger;
+	greeting: string;
+}
+
+const container = createContainer<Services>()
+	// 'greeting' can reference 'logger' even though it is registered later
+	.registerSingleton('greeting', r => {
+		r.resolve('logger').log('Building greeting...');
+		return 'Hello!';
+	})
+	.registerSingleton('logger', () => new Logger());
+
+const greeting = container.resolve('greeting');
+//    ^? string
+```
+
+You can mix both approaches — use class tokens for order-dependent type safety and PropertyKey tokens for order-independent flexibility:
+
+```ts
+const container = createContainer<Services>()
+	.registerSingleton(Logger, () => new Logger())
+	.registerSingleton('logger', () => new Logger())
+	.registerSingleton('greeting', r => {
+		r.resolve(Logger).log('Building greeting...');
+		return 'Hello!';
+	});
+```
+
+## API
+
+### `createContainer<T>()`
+
+Creates a new DI container. Pass an interface as `T` to define the type map for PropertyKey tokens.
+
+### `container.registerSingleton(token, factory)`
+
+Registers a factory as a singleton. The instance is created on the first `resolve` and cached thereafter. Returns the container for method chaining.
+
+### `container.registerTransient(token, factory)`
+
+Registers a factory as transient. A new instance is created on every `resolve`. Returns the container for method chaining.
+
+### `container.resolve(token)`
+
+Resolves and returns the instance for the given token. Throws `ContainerError` if the token is not registered.
+
+### `ContainerError`
+
+Error class thrown when resolving an unregistered token.
+
+## License
+
+MIT

package/dist/container.d.ts

@@ -0,0 +1,102 @@
+type AbstractConstructor<T = unknown> = abstract new (...args: never[]) => T;
+/**
+ * Resolver passed to factory callbacks.
+ *
+ * @template T PropertyKey-based type map (defined via interface, order-independent)
+ * @template C Union of registered class constructors (order-dependent)
+ */
+export interface Resolver<T, C extends AbstractConstructor = AbstractConstructor, AC extends AbstractConstructor = never> {
+    /**
+     * Resolve an instance for the given token.
+     *
+     * @param token A registered token
+     * @returns The instance associated with the token
+     */
+    resolve<V>(token: AbstractConstructor<V> & AC): Promise<V>;
+    resolve<V>(token: AbstractConstructor<V> & C): V;
+    resolve<K extends keyof T>(token: K): T[K];
+}
+/**
+ * Create a new DI container.
+ *
+ * Pass an interface as generic T to fix the PropertyKey token type map upfront (order-independent).
+ * Class tokens are accumulated via registerSingleton/registerTransient method chaining (order-dependent).
+ *
+ * @example
+ * ```ts
+ * interface Services { SampleController: string }
+ * const c = createContainer<Services>()
+ *   .registerSingleton(TextGenerationService, () => new MastraTextGenerationService())
+ *   .registerTransient(GenerateTextUseCase, r => new GenerateTextUseCase(r.resolve(TextGenerationService)));
+ * ```
+ */
+export declare function createContainer<T = Record<never, never>>(): Container<T>;
+/**
+ * Lightweight DI container.
+ *
+ * Provides type inference through method chaining with registerSingleton/registerTransient/resolve.
+ *
+ * - Singleton: Creates the instance on the first resolve and returns the cached value thereafter.
+ * - Transient: Creates a new instance via the factory function on every resolve.
+ *
+ * @template T PropertyKey-based token type map (defined via interface, order-independent)
+ * @template C Union of registered class constructors (accumulated via chaining, order-dependent)
+ */
+export declare class Container<T = Record<never, never>, C extends AbstractConstructor = never, AC extends AbstractConstructor = never> {
+    /**
+     * Convert a token to a human-readable string.
+     */
+    private static tokenToString;
+    private readonly registrations;
+    private readonly instances;
+    constructor();
+    /**
+     * Register a factory function as a singleton for the given token.
+     *
+     * Creates the instance on the first resolve and returns the cached value thereafter.
+     *
+     * @param token Any value to use as a token
+     * @param factory Factory function that receives a resolver and returns an instance
+     * @returns The container for method chaining
+     */
+    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, C, AC>) => Promise<V>): Container<T, C, AC | AbstractConstructor<V>>;
+    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, C, AC>) => V): Container<T, C | AbstractConstructor<V>, AC>;
+    registerSingleton<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, C, AC>) => V): Container<Record<K, V> & T, C, AC>;
+    registerSingleton<V>(token: unknown, factory: (resolver: Resolver<T, C, AC>) => V): Container<T, C, AC>;
+    /**
+     * Register a factory function as transient for the given token.
+     *
+     * Creates a new instance via the factory function on every resolve.
+     *
+     * @param token Any value to use as a token
+     * @param factory Factory function that receives a resolver and returns an instance
+     * @returns The container for method chaining
+     */
+    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, C, AC>) => Promise<V>): Container<T, C, AC | AbstractConstructor<V>>;
+    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, C, AC>) => V): Container<T, C | AbstractConstructor<V>, AC>;
+    registerTransient<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, C, AC>) => V): Container<Record<K, V> & T, C, AC>;
+    registerTransient<V>(token: unknown, factory: (resolver: Resolver<T, C, AC>) => V): Container<T, C, AC>;
+    /**
+     * Resolve an instance for the given token.
+     *
+     * For singleton registrations, creates the instance on the first call and caches it.
+     * For transient registrations, creates a new instance on every call.
+     *
+     * @param token A registered token
+     * @returns The instance associated with the token
+     * @throws ContainerError if the token is not registered
+     */
+    resolve<V>(token: AbstractConstructor<V> & AC): Promise<V>;
+    resolve<V>(token: AbstractConstructor<V> & C): V;
+    resolve<K extends keyof T>(token: K): T[K];
+    /**
+     * Add a registration entry.
+     *
+     * @param token Token
+     * @param factory Factory function
+     * @param singleton Whether to register as a singleton
+     * @returns The container for method chaining
+     */
+    private addRegistration;
+}
+export {};

package/dist/error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error thrown by the DI container.
+ *
+ * Represents failures in container operations such as resolving an unregistered token.
+ */
+export declare class ContainerError extends Error {
+    /**
+     * @param message Error message
+     */
+    constructor(message: string);
+}

package/dist/index.cjs

@@ -0,0 +1,92 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  createContainer: () => createContainer,
+  ContainerError: () => ContainerError,
+  Container: () => Container
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/error.ts
+class ContainerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContainerError";
+  }
+}
+
+// src/container.ts
+function createContainer() {
+  return new Container;
+}
+
+class Container {
+  static tokenToString(token) {
+    if (typeof token === "function") {
+      return token.name || "anonymous function";
+    }
+    if (typeof token === "symbol") {
+      return token.toString();
+    }
+    return String(token);
+  }
+  registrations;
+  instances;
+  constructor() {
+    this.registrations = new Map;
+    this.instances = new Map;
+  }
+  registerSingleton(token, factory) {
+    return this.addRegistration(token, factory, true);
+  }
+  registerTransient(token, factory) {
+    return this.addRegistration(token, factory, false);
+  }
+  resolve(token) {
+    const cached = this.instances.get(token);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const factory = this.registrations.get(token);
+    if (factory === undefined) {
+      throw new ContainerError(`Token "${Container.tokenToString(token)}" is not registered.`);
+    }
+    const instance = factory.factory(this);
+    if (factory.singleton) {
+      this.instances.set(token, instance);
+    }
+    return instance;
+  }
+  addRegistration(token, factory, singleton) {
+    this.registrations.set(token, { factory, singleton });
+    return this;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Resolver } from './container';
+export { Container, createContainer } from './container';
+export { ContainerError } from './error';

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/error.ts
+class ContainerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContainerError";
+  }
+}
+
+// src/container.ts
+function createContainer() {
+  return new Container;
+}
+
+class Container {
+  static tokenToString(token) {
+    if (typeof token === "function") {
+      return token.name || "anonymous function";
+    }
+    if (typeof token === "symbol") {
+      return token.toString();
+    }
+    return String(token);
+  }
+  registrations;
+  instances;
+  constructor() {
+    this.registrations = new Map;
+    this.instances = new Map;
+  }
+  registerSingleton(token, factory) {
+    return this.addRegistration(token, factory, true);
+  }
+  registerTransient(token, factory) {
+    return this.addRegistration(token, factory, false);
+  }
+  resolve(token) {
+    const cached = this.instances.get(token);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const factory = this.registrations.get(token);
+    if (factory === undefined) {
+      throw new ContainerError(`Token "${Container.tokenToString(token)}" is not registered.`);
+    }
+    const instance = factory.factory(this);
+    if (factory.singleton) {
+      this.instances.set(token, instance);
+    }
+    return instance;
+  }
+  addRegistration(token, factory, singleton) {
+    this.registrations.set(token, { factory, singleton });
+    return this;
+  }
+}
+export {
+  createContainer,
+  ContainerError,
+  Container
+};

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export type AbstractConstructor<T = unknown> = abstract new (...args: never[]) => T;
+/**
+ * Resolver passed to factory callbacks.
+ *
+ * @template T PropertyKey-based type map (defined via interface, order-independent)
+ * @template C Union of registered class constructors (order-dependent)
+ */
+export interface Resolver<T, C extends AbstractConstructor = AbstractConstructor, AC extends AbstractConstructor = never> {
+    /**
+     * Resolve an instance for the given token.
+     *
+     * @param token A registered token
+     * @returns The instance associated with the token
+     */
+    resolve<V>(token: AbstractConstructor<V> & AC): Promise<V>;
+    resolve<V>(token: AbstractConstructor<V> & C): V;
+    resolve<K extends keyof T>(token: K): T[K];
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "katagami",
+	"version": "1.0.0",
+	"description": "Lightweight TypeScript DI container with full type inference",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"keywords": [
+		"dependency-injection",
+		"di",
+		"container",
+		"ioc",
+		"typescript"
+	],
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"scripts": {
+		"preinstall": "case \"$npm_config_user_agent\" in bun*) ;; *) echo 'Error: This project requires Bun. Install: https://bun.sh' >&2; exit 1;; esac",
+		"build": "bun run build:types && bun run build:esm && bun run build:cjs",
+		"build:types": "tsc",
+		"build:esm": "bun build ./src/index.ts --outdir dist --format esm",
+		"build:cjs": "bun build ./src/index.ts --outfile dist/index.cjs --format cjs",
+		"test": "bun test --coverage",
+		"prepublishOnly": "bun run build",
+		"check": "bun run typecheck && bun run format",
+		"lint": "biome lint .",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@types/bun": "^1.3.8"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"typescript": "^5.9.3"
+	}
+}