@djodjonx/neosyringe 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# @djodjonx/neosyringe
+
+The runtime library for NeoSyringe. Contains strict types and helper functions.
+
+## Installation
+
+```bash
+npm install @djodjonx/neosyringe
+```
+
+See [Documentation](https://djodjonx.github.io/neosyringe/).

package/dist/index.cjs

@@ -0,0 +1,7 @@
+const require_types = require('./types.cjs');
+
+exports.declareContainerTokens = require_types.declareContainerTokens;
+exports.defineBuilderConfig = require_types.defineBuilderConfig;
+exports.definePartialConfig = require_types.definePartialConfig;
+exports.useInterface = require_types.useInterface;
+exports.useProperty = require_types.useProperty;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty } from "./types.cjs";
+export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty } from "./types.mjs";
+export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty } from "./types.mjs";
+
+export { declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/types.cjs

@@ -0,0 +1,64 @@
+
+//#region src/types.ts
+/**
+* Runtime helper to define a partial configuration.
+*/
+function definePartialConfig(config) {
+	return config;
+}
+/**
+* Runtime helper to define the main builder configuration.
+* This function is replaced at compile-time by the generated container.
+*
+* @throws {Error} If called at runtime without the build plugin.
+*/
+function defineBuilderConfig(_config) {
+	throw new Error("NeoSyringe: defineBuilderConfig() called at runtime. This library requires the compiler plugin to generate the container. Ensure the plugin is configured in your build system (Vite, Rollup, Webpack).");
+}
+/**
+* Runtime helper to create an interface token.
+* This function is replaced at compile-time by a unique ID.
+*
+* @throws {Error} If called at runtime without compilation.
+*/
+function useInterface() {
+	throw new Error("NeoSyringe: useInterface<T>() called at runtime. The build plugin is missing.");
+}
+/**
+* Creates a property token for injecting primitive values into class constructors.
+* The token is bound to a specific class and parameter name for type-safety.
+*
+* @example
+* ```typescript
+* const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+*
+* defineBuilderConfig({
+*   injections: [
+*     { token: apiUrl, provider: () => 'http://localhost' },
+*     { token: ApiService }
+*   ]
+* });
+* ```
+*
+* @throws {Error} If called at runtime without compilation.
+*/
+function useProperty(targetClass, paramName) {
+	throw new Error(`NeoSyringe: useProperty(${targetClass.name}, '${paramName}') called at runtime. The build plugin is missing.`);
+}
+/**
+* Declares the tokens provided by a legacy container.
+* This is a type-level helper; it returns the container instance as-is at runtime.
+*
+* @template T - A map of Token -> Type provided by the container.
+* @param container - The legacy container instance.
+*/
+function declareContainerTokens(container) {
+	return container;
+}
+
+//#endregion
+exports.declareContainerTokens = declareContainerTokens;
+exports.defineBuilderConfig = defineBuilderConfig;
+exports.definePartialConfig = definePartialConfig;
+exports.useInterface = useInterface;
+exports.useProperty = useProperty;

package/dist/types.d.cts

@@ -0,0 +1,161 @@
+//#region src/types.d.ts
+/**
+ * Represents a generic class constructor.
+ * @template T - The type of the instance created by the constructor.
+ */
+type Constructor<T = any> = new (...args: any[]) => T;
+/**
+ * Defines the lifecycle of a service.
+ * - `singleton`: One instance per container.
+ * - `transient`: A new instance every time it is resolved.
+ */
+type Lifecycle = 'singleton' | 'transient';
+/**
+ * The dependency injection container interface.
+ * Provides access to the registered services.
+ */
+interface Container {
+  /**
+       * Resolves a service by its token.
+       *
+       * @template T - The type of the service to resolve.
+       * @param token - The service token (class constructor, interface token, or property token).
+       * @returns The resolved service instance.
+       * @throws {Error} If the service is not found or not registered.
+       */
+  resolve<T>(token: Token<T>): T;
+}
+/**
+ * A unique token for an interface, generated at compile-time.
+ */
+type InterfaceToken<T> = {
+  __brand: 'InterfaceToken';
+  __type: T;
+};
+/**
+ * A unique token for a primitive property bound to a specific class parameter.
+ * Used for injecting string, number, boolean, etc. into class constructors.
+ */
+type PropertyToken<T, C = unknown> = {
+  __brand: 'PropertyToken';
+  __type: T;
+  __class: C;
+  __name: string;
+};
+/**
+ * Represents a token that can be injected.
+ * Can be a Class Constructor, an Interface Token, or a Property Token.
+ */
+type Token<T = any> = Constructor<T> | InterfaceToken<T> | PropertyToken<T, any>;
+/**
+ * A factory function that creates an instance.
+ * Receives the container to resolve dependencies.
+ */
+type Factory<T> = (container: Container) => T;
+/**
+ * A provider can be a class constructor or a factory function.
+ */
+type Provider<T> = Constructor<T> | Factory<T>;
+/**
+ * Definition of a single injection.
+ */
+interface Injection<T = any> {
+  token: Token<T>;
+  provider?: Provider<T>;
+  /**
+       * If true, the provider is treated as a factory function.
+       * Required when provider is a function, not a class.
+       */
+  useFactory?: boolean;
+  /**
+       * Lifecycle of the service.
+       * - `singleton`: One instance per container (default).
+       * - `transient`: A new instance every time it is resolved.
+       */
+  lifecycle?: Lifecycle;
+  /**
+       * If true, this injection is scoped to this container only.
+       * Allows overriding a token from a parent container without causing a duplicate error.
+       * The local instance will be used instead of delegating to the parent.
+       *
+       * @example
+       * ```typescript
+       * const parent = defineBuilderConfig({
+       *   injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+       * });
+       *
+       * const child = defineBuilderConfig({
+       *   useContainer: parent,
+       *   injections: [
+       *     // Override parent's ILogger with a local FileLogger
+       *     { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+       *   ]
+       * });
+       * ```
+       */
+  scoped?: boolean;
+}
+/**
+ * Partial configuration that can be shared/extended.
+ */
+interface PartialConfig {
+  injections?: Injection[];
+}
+/**
+ * Main configuration for a container builder.
+ */
+interface BuilderConfig extends PartialConfig {
+  name?: string;
+  extends?: PartialConfig[];
+  /**
+       * Parent container instance to bridge (NeoSyringe or legacy).
+       */
+  useContainer?: any;
+}
+/**
+ * Runtime helper to define a partial configuration.
+ */
+declare function definePartialConfig(config: PartialConfig): PartialConfig;
+/**
+ * Runtime helper to define the main builder configuration.
+ * This function is replaced at compile-time by the generated container.
+ *
+ * @throws {Error} If called at runtime without the build plugin.
+ */
+declare function defineBuilderConfig(_config: BuilderConfig): Container;
+/**
+ * Runtime helper to create an interface token.
+ * This function is replaced at compile-time by a unique ID.
+ *
+ * @throws {Error} If called at runtime without compilation.
+ */
+declare function useInterface<T>(): InterfaceToken<T>;
+/**
+ * Creates a property token for injecting primitive values into class constructors.
+ * The token is bound to a specific class and parameter name for type-safety.
+ *
+ * @example
+ * ```typescript
+ * const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+ *
+ * defineBuilderConfig({
+ *   injections: [
+ *     { token: apiUrl, provider: () => 'http://localhost' },
+ *     { token: ApiService }
+ *   ]
+ * });
+ * ```
+ *
+ * @throws {Error} If called at runtime without compilation.
+ */
+declare function useProperty<T, C extends Constructor<any>>(targetClass: C, paramName: string): PropertyToken<T, InstanceType<C>>;
+/**
+ * Declares the tokens provided by a legacy container.
+ * This is a type-level helper; it returns the container instance as-is at runtime.
+ *
+ * @template T - A map of Token -> Type provided by the container.
+ * @param container - The legacy container instance.
+ */
+declare function declareContainerTokens<T extends Record<string, any>>(container: any): T & { [K in keyof T]: T[K] };
+//#endregion
+export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/types.d.mts

@@ -0,0 +1,161 @@
+//#region src/types.d.ts
+/**
+ * Represents a generic class constructor.
+ * @template T - The type of the instance created by the constructor.
+ */
+type Constructor<T = any> = new (...args: any[]) => T;
+/**
+ * Defines the lifecycle of a service.
+ * - `singleton`: One instance per container.
+ * - `transient`: A new instance every time it is resolved.
+ */
+type Lifecycle = 'singleton' | 'transient';
+/**
+ * The dependency injection container interface.
+ * Provides access to the registered services.
+ */
+interface Container {
+  /**
+       * Resolves a service by its token.
+       *
+       * @template T - The type of the service to resolve.
+       * @param token - The service token (class constructor, interface token, or property token).
+       * @returns The resolved service instance.
+       * @throws {Error} If the service is not found or not registered.
+       */
+  resolve<T>(token: Token<T>): T;
+}
+/**
+ * A unique token for an interface, generated at compile-time.
+ */
+type InterfaceToken<T> = {
+  __brand: 'InterfaceToken';
+  __type: T;
+};
+/**
+ * A unique token for a primitive property bound to a specific class parameter.
+ * Used for injecting string, number, boolean, etc. into class constructors.
+ */
+type PropertyToken<T, C = unknown> = {
+  __brand: 'PropertyToken';
+  __type: T;
+  __class: C;
+  __name: string;
+};
+/**
+ * Represents a token that can be injected.
+ * Can be a Class Constructor, an Interface Token, or a Property Token.
+ */
+type Token<T = any> = Constructor<T> | InterfaceToken<T> | PropertyToken<T, any>;
+/**
+ * A factory function that creates an instance.
+ * Receives the container to resolve dependencies.
+ */
+type Factory<T> = (container: Container) => T;
+/**
+ * A provider can be a class constructor or a factory function.
+ */
+type Provider<T> = Constructor<T> | Factory<T>;
+/**
+ * Definition of a single injection.
+ */
+interface Injection<T = any> {
+  token: Token<T>;
+  provider?: Provider<T>;
+  /**
+       * If true, the provider is treated as a factory function.
+       * Required when provider is a function, not a class.
+       */
+  useFactory?: boolean;
+  /**
+       * Lifecycle of the service.
+       * - `singleton`: One instance per container (default).
+       * - `transient`: A new instance every time it is resolved.
+       */
+  lifecycle?: Lifecycle;
+  /**
+       * If true, this injection is scoped to this container only.
+       * Allows overriding a token from a parent container without causing a duplicate error.
+       * The local instance will be used instead of delegating to the parent.
+       *
+       * @example
+       * ```typescript
+       * const parent = defineBuilderConfig({
+       *   injections: [{ token: useInterface<ILogger>(), provider: ConsoleLogger }]
+       * });
+       *
+       * const child = defineBuilderConfig({
+       *   useContainer: parent,
+       *   injections: [
+       *     // Override parent's ILogger with a local FileLogger
+       *     { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+       *   ]
+       * });
+       * ```
+       */
+  scoped?: boolean;
+}
+/**
+ * Partial configuration that can be shared/extended.
+ */
+interface PartialConfig {
+  injections?: Injection[];
+}
+/**
+ * Main configuration for a container builder.
+ */
+interface BuilderConfig extends PartialConfig {
+  name?: string;
+  extends?: PartialConfig[];
+  /**
+       * Parent container instance to bridge (NeoSyringe or legacy).
+       */
+  useContainer?: any;
+}
+/**
+ * Runtime helper to define a partial configuration.
+ */
+declare function definePartialConfig(config: PartialConfig): PartialConfig;
+/**
+ * Runtime helper to define the main builder configuration.
+ * This function is replaced at compile-time by the generated container.
+ *
+ * @throws {Error} If called at runtime without the build plugin.
+ */
+declare function defineBuilderConfig(_config: BuilderConfig): Container;
+/**
+ * Runtime helper to create an interface token.
+ * This function is replaced at compile-time by a unique ID.
+ *
+ * @throws {Error} If called at runtime without compilation.
+ */
+declare function useInterface<T>(): InterfaceToken<T>;
+/**
+ * Creates a property token for injecting primitive values into class constructors.
+ * The token is bound to a specific class and parameter name for type-safety.
+ *
+ * @example
+ * ```typescript
+ * const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+ *
+ * defineBuilderConfig({
+ *   injections: [
+ *     { token: apiUrl, provider: () => 'http://localhost' },
+ *     { token: ApiService }
+ *   ]
+ * });
+ * ```
+ *
+ * @throws {Error} If called at runtime without compilation.
+ */
+declare function useProperty<T, C extends Constructor<any>>(targetClass: C, paramName: string): PropertyToken<T, InstanceType<C>>;
+/**
+ * Declares the tokens provided by a legacy container.
+ * This is a type-level helper; it returns the container instance as-is at runtime.
+ *
+ * @template T - A map of Token -> Type provided by the container.
+ * @param container - The legacy container instance.
+ */
+declare function declareContainerTokens<T extends Record<string, any>>(container: any): T & { [K in keyof T]: T[K] };
+//#endregion
+export { BuilderConfig, Constructor, Container, Factory, Injection, InterfaceToken, Lifecycle, PartialConfig, PropertyToken, Provider, Token, declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/dist/types.mjs

@@ -0,0 +1,59 @@
+//#region src/types.ts
+/**
+* Runtime helper to define a partial configuration.
+*/
+function definePartialConfig(config) {
+	return config;
+}
+/**
+* Runtime helper to define the main builder configuration.
+* This function is replaced at compile-time by the generated container.
+*
+* @throws {Error} If called at runtime without the build plugin.
+*/
+function defineBuilderConfig(_config) {
+	throw new Error("NeoSyringe: defineBuilderConfig() called at runtime. This library requires the compiler plugin to generate the container. Ensure the plugin is configured in your build system (Vite, Rollup, Webpack).");
+}
+/**
+* Runtime helper to create an interface token.
+* This function is replaced at compile-time by a unique ID.
+*
+* @throws {Error} If called at runtime without compilation.
+*/
+function useInterface() {
+	throw new Error("NeoSyringe: useInterface<T>() called at runtime. The build plugin is missing.");
+}
+/**
+* Creates a property token for injecting primitive values into class constructors.
+* The token is bound to a specific class and parameter name for type-safety.
+*
+* @example
+* ```typescript
+* const apiUrl = useProperty<string>(ApiService, 'apiUrl');
+*
+* defineBuilderConfig({
+*   injections: [
+*     { token: apiUrl, provider: () => 'http://localhost' },
+*     { token: ApiService }
+*   ]
+* });
+* ```
+*
+* @throws {Error} If called at runtime without compilation.
+*/
+function useProperty(targetClass, paramName) {
+	throw new Error(`NeoSyringe: useProperty(${targetClass.name}, '${paramName}') called at runtime. The build plugin is missing.`);
+}
+/**
+* Declares the tokens provided by a legacy container.
+* This is a type-level helper; it returns the container instance as-is at runtime.
+*
+* @template T - A map of Token -> Type provided by the container.
+* @param container - The legacy container instance.
+*/
+function declareContainerTokens(container) {
+	return container;
+}
+
+//#endregion
+export { declareContainerTokens, defineBuilderConfig, definePartialConfig, useInterface, useProperty };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@djodjonx/neosyringe",
+  "version": "0.1.0",
+  "description": "Runtime library for NeoSyringe DI",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "0.20.0-beta.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}