di-sacala 0.1.0 → 0.1.2

package/README.md

@@ -9,6 +9,7 @@
 - **Full Type Safety**: Get autocompletion and type checks for all your injected services.
 - **Fluent API**: Chainable service registration makes it easy to compose your container.
 - **Container Composition**: Merge multiple containers together to share dependencies across different parts of your application.
+- **Lazy & Singleton**: Services are instantiated only on demand (when first accessed) and reused for subsequent accesses.
 - **Zero Runtime Dependencies**: Extremely lightweight.
 
 ## Installation
@@ -21,13 +22,15 @@ npm install di-sacala
 
 ### 1. Defining a Service
 
-A service is a class that implements the `DiService` interface. It must have a `name` property which will be used as the key in the container. Use `as const` to ensure the name is treated as a literal type.
+A service is a class that implements the `DiService` interface. It must implement a `getServiceName()` method which will be used as the key in the container. Use `as const` to ensure the name is treated as a literal type.
 
 ```typescript
 import { DiService } from 'di-sacala';
 
 export class LoggerService implements DiService<"logger"> {
-    name = "logger" as const;
+    getServiceName() {
+        return "logger" as const;
+    }
     
     log(message: string) {
         console.log(`[LOG]: ${message}`);
@@ -52,14 +55,16 @@ container.logger.log("Service is ready!");
 
 ### 3. Services with Dependencies
 
-To inject dependencies into a service, define its constructor to accept the container. You can use the `Di` type helper to specify which services are required.
+To inject dependencies into a service, define its constructor to accept the container. You can use the `Di<T>` type helper to specify which services are required. It supports both a single service type or a tuple of multiple services.
 
 ```typescript
 import { Di, DiService } from 'di-sacala';
 import { LoggerService } from './LoggerService';
 
 export class UserService implements DiService<"user"> {
-    name = "user" as const;
+    getServiceName() {
+        return "user" as const;
+    }
     
     // Use Di<ServiceType> or Di<[Service1, Service2]> for type-safe dependencies
     constructor(private di: Di<LoggerService>) {}
@@ -91,6 +96,59 @@ const appContainer = new DiContainer()
     .inject(MainApp);
 ```
 
+### 5. Lazy & Singleton
+
+Services registered via `inject` are only instantiated when they are first accessed. Once created, the same instance is returned for all subsequent calls. This ensures efficiency and consistent state within the container.
+
+```typescript
+const container = new DiContainer()
+    .inject(ExpensiveService);
+
+// ExpensiveService is NOT instantiated yet
+
+console.log("Container ready");
+
+// ExpensiveService is instantiated NOW
+container.expensive.doSomething();
+```
+
+### 6. Duplicate Service Name Protection
+
+`di-sacala` prevents registering multiple services with the same name. This protection works at both compile-time and runtime:
+
+- **Type-level Check**: If you try to `inject` a service with a name that already exists in the container, TypeScript will report an error, and the resulting type will be a string literal describing the error.
+- **Runtime Check**: The `inject` and `injectContainer` methods will throw an `Error` if a duplicate key is detected.
+
+```typescript
+const container = new DiContainer()
+    .inject(LoggerService);
+
+// TypeScript Error: Type '"Duplicate service name: logger"' ...
+// Runtime Error: Duplicate service name: logger
+container.inject(AnotherLoggerService); 
+```
+
+### 7. Reserved Field Names
+
+Since `DiContainer` uses a fluent API, certain names are reserved for its internal methods and cannot be used as service names:
+
+- `inject`
+- `injectContainer`
+
+Similar to duplicate names, attempting to use a reserved name will trigger both a **Type-level Check** and a **Runtime Check**.
+
+```typescript
+class InjectService implements DiService<"inject"> {
+    getServiceName() { return "inject" as const; }
+}
+
+const container = new DiContainer();
+
+// TypeScript Error: Type '"Reserved field name: inject"' ...
+// Runtime Error: Reserved field name: inject
+container.inject(InjectService);
+```
+
 ## Development
 
 ### Installation

package/dist/di-sacala.d.ts

@@ -3,7 +3,13 @@
  * The `name` property is used as the key when the service is injected into a DiContainer.
  */
 export interface DiService<Name extends string> {
-    name: Name;
+    /**
+     * The name of the service.
+     * This is used as the key when the service is injected into a DiContainer.
+     *
+     * The method is called without an instance context, so it can be used as a static property.
+     */
+    getServiceName(this: null): Name;
 }
 /**
  * A recursive type transformation that converts a Service (or tuple of Services)
@@ -15,6 +21,11 @@ export interface DiService<Name extends string> {
 export type Di<S> = S extends [infer S1, ...infer Tail] ? Di<S1> & Di<Tail> : S extends [] ? unknown : S extends DiService<infer Name> ? {
     [Key in Name]: S;
 } : never;
+type CheckReservedField<Name, T> = Name extends keyof DiContainer ? `Reserved field name: ${Name}` : T;
+type Append<Container, Service extends DiService<string>> = Service extends DiService<infer Name> ? CheckReservedField<Name, Container extends {
+    [Key in Name]: unknown;
+} ? `Duplicate service name: ${Name}` : Container & Di<Service>> : never;
+type Merge<DI1, DI2> = Exclude<keyof DI1, "inject" | "injectContainer"> & Exclude<keyof DI2, "inject" | "injectContainer"> extends never ? DI1 & DI2 : `Containers have duplicated keys: ${(Exclude<keyof DI1, "inject" | "injectContainer"> & Exclude<keyof DI2, "inject" | "injectContainer">) & string}`;
 /**
  * DiContainer manages service instantiation and dependency resolution.
  * It uses a fluent interface to chain service registrations, dynamically
@@ -29,8 +40,9 @@ export declare class DiContainer {
      * @template S - The type of service being injected.
      * @param dependency - A constructor for the service, which receives the container as its only argument.
      * @returns The container instance, typed with the newly added service.
+     * @throws {Error} If a service with the same name is already registered.
      */
-    inject<S extends DiService<string>>(dependency: new (dependencies: this) => S): this & Di<S>;
+    inject<S extends DiService<string>>(dependency: new (dependencies: this) => S): Append<this, S>;
     /**
      * Copies all service properties from another container into this one.
      * Useful for composing containers or providing shared dependencies.
@@ -38,7 +50,9 @@ export declare class DiContainer {
      * @template DC - The type of the other DiContainer.
      * @param other - The source container to copy services from.
      * @returns The current container instance, typed with the merged services.
+     * @throws {Error} If any service name from the other container already exists in this container.
      */
-    injectContainer<DC extends DiContainer>(other: DC): this & DC;
+    injectContainer<DC extends DiContainer>(other: DC): Merge<this, DC>;
 }
+export {};
 //# sourceMappingURL=di-sacala.d.ts.map

package/dist/di-sacala.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"di-sacala.d.ts","sourceRoot":"","sources":["../src/di-sacala.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,IAAI,SAAS,MAAM;IAC1C,IAAI,EAAE,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,GACjD,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GACjB,CAAC,SAAS,EAAE,GACV,OAAO,GACP,CAAC,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,GAC7B;KAAG,GAAG,IAAI,IAAI,GAAG,CAAC;CAAE,GACpB,KAAK,CAAC;AAEhB;;;;GAIG;AACH,qBAAa,WAAW;;IAGpB;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;IAM5F;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,WAAW,EAAE,KAAK,EAAE,EAAE,GAAG,IAAI,GAAG,EAAE;CAQhE"}
+{"version":3,"file":"di-sacala.d.ts","sourceRoot":"","sources":["../src/di-sacala.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,IAAI,SAAS,MAAM;IAC1C;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,GACjD,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GACjB,CAAC,SAAS,EAAE,GACV,OAAO,GACP,CAAC,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,GAC7B;KAAG,GAAG,IAAI,IAAI,GAAG,CAAC;CAAE,GACpB,KAAK,CAAC;AAIhB,KAAK,kBAAkB,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI,SAAS,MAAM,WAAW,GAC3D,wBAAwB,IAAI,EAAE,GAC9B,CAAC,CAAC;AAER,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,SAAS,SAAS,CAAC,MAAM,CAAC,IACpD,OAAO,SAAS,SAAS,CAAC,MAAM,IAAI,CAAC,GAC/B,kBAAkB,CACd,IAAI,EACJ,SAAS,SAAS;KAAG,GAAG,IAAI,IAAI,GAAG,OAAO;CAAE,GACtC,2BAA2B,IAAI,EAAE,GACjC,SAAS,GAAG,EAAE,CAAC,OAAO,CAAC,CAChC,GACD,KAAK,CAAC;AAEhB,KAAK,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,CAAC,MAAM,GAAG,EAAE,QAAQ,GAAG,iBAAiB,CAAC,GACnE,OAAO,CAAC,MAAM,GAAG,EAAE,QAAQ,GAAG,iBAAiB,CAAC,SAAS,KAAK,GAC5D,GAAG,GAAG,GAAG,GACT,oCAAoC,CAAC,OAAO,CACxC,MAAM,GAAG,EACT,QAAQ,GAAG,iBAAiB,CAC/B,GACG,OAAO,CAAC,MAAM,GAAG,EAAE,QAAQ,GAAG,iBAAiB,CAAC,CAAC,GACjD,MAAM,EAAE,CAAC;AAKnB;;;;GAIG;AACH,qBAAa,WAAW;;IAGpB;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAC9B,UAAU,EAAE,KAAK,YAAY,EAAE,IAAI,KAAK,CAAC,GAC1C,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAyBlB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,SAAS,WAAW,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;CAoBtE"}

package/dist/index.js

@@ -1,4 +1,5 @@
-class i {
+const s = /* @__PURE__ */ new Set(["inject", "injectContainer"]), r = (n, t) => Object.prototype.hasOwnProperty.call(n, t);
+class o {
   constructor() {
   }
   /**
@@ -8,10 +9,20 @@ class i {
    * @template S - The type of service being injected.
    * @param dependency - A constructor for the service, which receives the container as its only argument.
    * @returns The container instance, typed with the newly added service.
+   * @throws {Error} If a service with the same name is already registered.
    */
-  inject(n) {
-    const t = new n(this);
-    return this[t.name] = t, this;
+  inject(t) {
+    const e = t.prototype.getServiceName();
+    if (s.has(e))
+      throw new Error(`Reserved field name: ${e}`);
+    if (r(this, e))
+      throw new Error(`Duplicate service name: ${e}`);
+    let i;
+    return Object.defineProperty(this, e, {
+      enumerable: !0,
+      configurable: !1,
+      get: () => i ?? (i = new t(this))
+    }), this;
   }
   /**
    * Copies all service properties from another container into this one.
@@ -20,13 +31,21 @@ class i {
    * @template DC - The type of the other DiContainer.
    * @param other - The source container to copy services from.
    * @returns The current container instance, typed with the merged services.
+   * @throws {Error} If any service name from the other container already exists in this container.
    */
-  injectContainer(n) {
-    for (const t in n)
-      Object.prototype.hasOwnProperty.call(n, t) && (this[t] = n[t]);
+  injectContainer(t) {
+    for (const e in t)
+      if (r(t, e) && r(this, e))
+        throw new Error(`Containers have duplicated keys: ${e}`);
+    for (const e in t)
+      r(t, e) && Object.defineProperty(this, e, {
+        enumerable: !0,
+        configurable: !1,
+        get: () => t[e]
+      });
     return this;
   }
 }
 export {
-  i as DiContainer
+  o as DiContainer
 };

package/dist/index.umd.cjs

@@ -1 +1 @@
-(function(e,n){typeof exports=="object"&&typeof module<"u"?n(exports):typeof define=="function"&&define.amd?define(["exports"],n):(e=typeof globalThis<"u"?globalThis:e||self,n(e.DiSacala={}))})(this,(function(e){"use strict";class n{constructor(){}inject(i){const t=new i(this);return this[t.name]=t,this}injectContainer(i){for(const t in i)Object.prototype.hasOwnProperty.call(i,t)&&(this[t]=i[t]);return this}}e.DiContainer=n,Object.defineProperty(e,Symbol.toStringTag,{value:"Module"})}));
+(function(n,i){typeof exports=="object"&&typeof module<"u"?i(exports):typeof define=="function"&&define.amd?define(["exports"],i):(n=typeof globalThis<"u"?globalThis:n||self,i(n.DiSacala={}))})(this,(function(n){"use strict";const i=new Set(["inject","injectContainer"]),r=(o,t)=>Object.prototype.hasOwnProperty.call(o,t);class a{constructor(){}inject(t){const e=t.prototype.getServiceName();if(i.has(e))throw new Error(`Reserved field name: ${e}`);if(r(this,e))throw new Error(`Duplicate service name: ${e}`);let s;return Object.defineProperty(this,e,{enumerable:!0,configurable:!1,get:()=>s??(s=new t(this))}),this}injectContainer(t){for(const e in t)if(r(t,e)&&r(this,e))throw new Error(`Containers have duplicated keys: ${e}`);for(const e in t)r(t,e)&&Object.defineProperty(this,e,{enumerable:!0,configurable:!1,get:()=>t[e]});return this}}n.DiContainer=a,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,38 +1,38 @@
 {
-  "name": "di-sacala",
-  "version": "0.1.0",
-  "description": "Small type-safe dependency injection lib",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint src --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\""
-  },
-  "keywords": [],
-  "author": {
-    "name": "Andrei Monkin",
-    "email": "monkin.andrey@gmail.com",
-    "url": "https://github.com/monkin"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^25.0.9",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "eslint": "^9.39.2",
-    "prettier": "^3.8.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.0.17"
-  }
+    "name": "di-sacala",
+    "version": "0.1.2",
+    "description": "Small type-safe dependency injection lib",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "vite build",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "eslint src --ext .ts",
+        "format": "prettier --write \"src/**/*.ts\"",
+        "format:check": "prettier --check \"src/**/*.ts\""
+    },
+    "keywords": [],
+    "author": {
+        "name": "Andrei Monkin",
+        "email": "monkin.andrey@gmail.com",
+        "url": "https://github.com/monkin"
+    },
+    "license": "MIT",
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "@types/node": "^25.0.9",
+        "@typescript-eslint/eslint-plugin": "^8.53.0",
+        "@typescript-eslint/parser": "^8.53.0",
+        "eslint": "^9.39.2",
+        "prettier": "^3.8.0",
+        "typescript": "^5.9.3",
+        "vite": "^7.3.1",
+        "vite-plugin-dts": "^4.5.4",
+        "vitest": "^4.0.17"
+    }
 }