@khapu2906/treasure-chest 1.0.2

package/LICENSE

@@ -0,0 +1,40 @@
+DIB License v1.0
+Copyright (c) 2025 Developers in Black (DIB)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software, subject to the following conditions:
+
+1. Attribution
+   - Any use, modification, or distribution must include clear attribution to
+     Developers in Black (DIB).
+   - Original authorship and license text must be preserved.
+
+2. Modification
+   - Modified versions (derivative works) are permitted.
+   - Modifiers must clearly state that their work is based on the original
+     Software by DIB.
+
+3. Commercial Use
+   - The Software may be used within commercial products and services.
+   - However, direct commercial resale of the Software itself, whether
+     modified or unmodified, is strictly prohibited.
+   - Integration of the Software into larger systems or products that are
+     commercialized is permitted.
+
+4. Third Parties
+   - Redistribution or sublicensing of the Software that violates these
+     conditions requires explicit written approval from Developers in Black.
+
+5. Author Information
+   - Any public or private use of this Software must retain the name of
+     Developers in Black (DIB) as the original author.
+
+6. Disclaimer
+   - 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,176 @@
+# Treasure Chest
+
+A simple and powerful TypeScript dependency injection container.
+
+## Installation
+
+```bash
+npm install treasure-chest
+```
+
+## Basic Usage
+
+```typescript
+import { Container } from 'treasure-chest';
+
+const container = new Container();
+
+// Register a service
+container.bind('logger', () => ({
+  log: (message: string) => console.log(`[LOG] ${message}`)
+}));
+
+// Use the service
+const logger = container.resolve('logger');
+logger.log('Hello World!');
+```
+
+## Key Features
+
+### 1. Bind (Transient)
+Creates a new instance on each resolve:
+
+```typescript
+container.bind('service', () => ({ id: Math.random() }));
+
+const instance1 = container.resolve('service');
+const instance2 = container.resolve('service');
+console.log(instance1.id !== instance2.id); // true
+```
+
+### 2. Singleton
+Creates only one instance:
+
+```typescript
+container.singleton('cache', () => ({ data: {} }));
+
+const cache1 = container.resolve('cache');
+const cache2 = container.resolve('cache');
+console.log(cache1 === cache2); // true
+```
+
+### 3. Alias
+Create aliases for services:
+
+```typescript
+container.singleton('logger', () => ({ log: console.log }));
+container.alias('appLogger', 'logger');
+
+const logger = container.resolve('appLogger'); // Same as 'logger'
+```
+
+### 4. Conditional Binding
+Register services based on conditions:
+
+```typescript
+const env = 'production';
+
+container.bind('storage', () => ({ type: 'local' }), () => env === 'development');
+container.bind('storage', () => ({ type: 's3' }), () => env === 'production');
+
+const storage = container.resolve('storage'); // { type: 's3' }
+```
+
+### 5. Contextual Binding
+Register different implementations for different contexts:
+
+```typescript
+container.when('UserService').needs('repository').give(() => new UserRepository());
+container.when('AdminService').needs('repository').give(() => new AdminRepository());
+
+const userRepo = container.resolve('repository', 'UserService'); // UserRepository
+const adminRepo = container.resolve('repository', 'AdminService'); // AdminRepository
+```
+
+## API Reference
+
+### Container Class
+
+#### `bind<T>(key: string, factory: FactoryFn<T>, condition?: ConditionFn)`
+Register a transient service.
+
+#### `singleton<T>(key: string, factory: FactoryFn<T>, condition?: ConditionFn)`
+Register a singleton service.
+
+#### `alias(aliasKey: string, originalKey: string)`
+Create an alias for a service.
+
+#### `resolve<T>(key: string, context?: string): T`
+Resolve a service from the container.
+
+#### `when(context: string)`
+Start a contextual binding chain.
+
+#### `reset()`
+Clear all bindings and instances (useful for testing).
+
+### Global Container
+
+```typescript
+import { container } from 'treasure-chest';
+
+// Use global container
+container.bind('config', () => ({ env: 'production' }));
+```
+
+## Real-world Example
+
+```typescript
+import { Container } from 'treasure-chest';
+
+class Database {
+  connect() {
+    return { status: 'connected' };
+  }
+}
+
+class UserRepository {
+  constructor(private db: Database) {}
+
+  findUser(id: number) {
+    return { id, name: 'John Doe' };
+  }
+}
+
+class UserService {
+  constructor(private repo: UserRepository) {}
+
+  getUser(id: number) {
+    return this.repo.findUser(id);
+  }
+}
+
+// Setup container
+const container = new Container();
+
+container.singleton('db', () => new Database());
+container.singleton('userRepo', (c) => new UserRepository(c.resolve('db')));
+container.singleton('userService', (c) => new UserService(c.resolve('userRepo')));
+
+// Contextual binding
+container.when('AdminService').needs('userRepo').give((c) => ({
+  ...c.resolve('userRepo'),
+  adminAccess: true
+}));
+
+// Usage
+const userService = container.resolve<UserService>('userService');
+console.log(userService.getUser(1)); // { id: 1, name: 'John Doe' }
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## License
+
+MIT</content>
+<filePath>/Users/daikhanhphung/K-Doc/Projects/Packages/treasure-chest/README.md

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Treasure Chest Service Container in TypeScript
+ * Supports:
+ *  - bind / singleton
+ *  - conditional binding
+ *  - contextual binding
+ *  - alias
+ *  - resolve
+ */
+type FactoryFn<T> = (c: Container) => T;
+type ConditionFn = (c: Container) => boolean;
+export declare class Container {
+    private bindings;
+    private instances;
+    private aliases;
+    private currentContext?;
+    /**
+     * Bind a dependency (default: transient)
+     */
+    bind<T>(key: string, factory: FactoryFn<T>, condition?: ConditionFn): void;
+    /**
+     * Bind a dependency as singleton (only one instance created)
+     */
+    singleton<T>(key: string, factory: FactoryFn<T>, condition?: ConditionFn): void;
+    /**
+     * Add an alias for an existing key
+     */
+    alias(aliasKey: string, originalKey: string): void;
+    /**
+     * Internal: find correct binding based on key + condition + context
+     */
+    private findBinding;
+    /**
+     * Resolve an instance from the container
+     */
+    resolve<T>(key: string, context?: string): T;
+    /**
+     * Contextual binding:
+     * Example:
+     *   container.when('UserService').needs('UserRepo').give(...)
+     */
+    when(context: string): {
+        needs: (depKey: string) => {
+            give: (factory: FactoryFn<any>) => void;
+        };
+    };
+    /**
+     * Clear all bindings and instances (useful for testing)
+     */
+    reset(): void;
+}
+export declare const container: Container;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,KAAK,CAAC,CAAC;AACxC,KAAK,WAAW,GAAG,CAAC,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC;AAU7C,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,cAAc,CAAC,CAAS;IAEhC;;OAEG;IACH,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,WAAW;IAInE;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,WAAW;IAIxE;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;IAI3C;;OAEG;IACH,OAAO,CAAC,WAAW;IAsBnB;;OAEG;IACH,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC;IA8B5C;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM;wBAEA,MAAM;4BACJ,SAAS,CAAC,GAAG,CAAC;;;IAYpC;;OAEG;IACH,KAAK;CAMN;AAGD,eAAO,MAAM,SAAS,WAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Treasure Chest Service Container in TypeScript
+ * Supports:
+ *  - bind / singleton
+ *  - conditional binding
+ *  - contextual binding
+ *  - alias
+ *  - resolve
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.container = exports.Container = void 0;
+class Container {
+    constructor() {
+        this.bindings = [];
+        this.instances = {};
+        this.aliases = {};
+    }
+    /**
+     * Bind a dependency (default: transient)
+     */
+    bind(key, factory, condition) {
+        this.bindings.push({ key, factory, singleton: false, condition });
+    }
+    /**
+     * Bind a dependency as singleton (only one instance created)
+     */
+    singleton(key, factory, condition) {
+        this.bindings.push({ key, factory, singleton: true, condition });
+    }
+    /**
+     * Add an alias for an existing key
+     */
+    alias(aliasKey, originalKey) {
+        this.aliases[aliasKey] = originalKey;
+    }
+    /**
+     * Internal: find correct binding based on key + condition + context
+     */
+    findBinding(key, context) {
+        const realKey = this.aliases[key] || key;
+        const bindings = this.bindings.filter((b) => b.key === realKey);
+        if (bindings.length === 0) {
+            throw new Error(`No binding found for key: ${realKey}`);
+        }
+        // Priority:
+        // 1. Binding with context and condition true
+        // 2. Binding without context but condition true
+        // 3. Binding default first
+        const match = bindings.find((b) => b.context === context && (!b.condition || b.condition(this))) ||
+            bindings.find((b) => !b.context && (!b.condition || b.condition(this))) ||
+            bindings[0];
+        return match;
+    }
+    /**
+     * Resolve an instance from the container
+     */
+    resolve(key, context) {
+        const prevContext = this.currentContext;
+        this.currentContext = context || key;
+        // Get real key (resolve alias)
+        const realKey = this.aliases[key] || key;
+        const binding = this.findBinding(key, this.currentContext);
+        // Create unique cache key for contextual singletons
+        const cacheKey = binding.context
+            ? `${realKey}::${binding.context}`
+            : realKey;
+        // Return existing singleton instance
+        if (binding.singleton && this.instances[cacheKey]) {
+            this.currentContext = prevContext;
+            return this.instances[cacheKey];
+        }
+        const instance = binding.factory(this);
+        if (binding.singleton) {
+            this.instances[cacheKey] = instance;
+        }
+        this.currentContext = prevContext;
+        return instance;
+    }
+    /**
+     * Contextual binding:
+     * Example:
+     *   container.when('UserService').needs('UserRepo').give(...)
+     */
+    when(context) {
+        return {
+            needs: (depKey) => ({
+                give: (factory) => {
+                    this.bindings.push({
+                        key: depKey,
+                        factory,
+                        singleton: false,
+                        context,
+                    });
+                },
+            }),
+        };
+    }
+    /**
+     * Clear all bindings and instances (useful for testing)
+     */
+    reset() {
+        this.bindings = [];
+        this.instances = {};
+        this.aliases = {};
+        this.currentContext = undefined;
+    }
+}
+exports.Container = Container;
+// Global container instance
+exports.container = new Container();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@khapu2906/treasure-chest",
+  "version": "1.0.2",
+  "description": "A container package for system utilities",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "container",
+    "system",
+    "utilities"
+  ],
+  "author": "Kent Phung",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khapu2906/treasure-chest.git"
+  },
+  "bugs": {
+    "url": "https://github.com/khapu2906/treasure-chest/issues"
+  },
+  "homepage": "https://github.com/khapu2906/treasure-chest#readme",
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "vitest": "^4.0.7",
+    "vittest": "^1.0.2"
+  }
+}