@djodjonx/neo-syringe 1.2.0 → 1.2.2

package/dist/cli/index.cjs

@@ -4,6 +4,21 @@ let typescript = require("typescript");
 typescript = require_GraphValidator.__toESM(typescript);
 
 //#region src/cli/index.ts
+/**
+* Neo-Syringe CLI
+*
+* Validates the dependency graph for a TypeScript project.
+* Detects circular dependencies, missing bindings, and duplicate registrations.
+*
+* @example
+* ```bash
+* npx neo-syringe
+* ```
+*/
+/**
+* CLI entry point.
+* Reads tsconfig.json, analyzes the project, and validates the dependency graph.
+*/
 function main() {
 	const cwd = process.cwd();
 	const configPath = typescript.findConfigFile(cwd, typescript.sys.fileExists, "tsconfig.json");

package/dist/cli/index.mjs

@@ -3,6 +3,21 @@ import { n as Analyzer, t as GraphValidator } from "../GraphValidator-DXqqkNdS.m
 import * as ts from "typescript";
 
 //#region src/cli/index.ts
+/**
+* Neo-Syringe CLI
+*
+* Validates the dependency graph for a TypeScript project.
+* Detects circular dependencies, missing bindings, and duplicate registrations.
+*
+* @example
+* ```bash
+* npx neo-syringe
+* ```
+*/
+/**
+* CLI entry point.
+* Reads tsconfig.json, analyzes the project, and validates the dependency graph.
+*/
 function main() {
 	const cwd = process.cwd();
 	const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json");

package/dist/index.d.cts

@@ -3,7 +3,7 @@
  * Represents a generic class constructor.
  * @template T - The type of the instance created by the constructor.
  */
-type Constructor<T = unknown> = new (...args: unknown[]) => T;
+type Constructor<T = any> = new (...args: any[]) => T;
 /**
  * Defines the lifecycle of a service.
  * - `singleton`: One instance per container.

package/dist/index.d.mts

@@ -3,7 +3,7 @@
  * Represents a generic class constructor.
  * @template T - The type of the instance created by the constructor.
  */
-type Constructor<T = unknown> = new (...args: unknown[]) => T;
+type Constructor<T = any> = new (...args: any[]) => T;
 /**
  * Defines the lifecycle of a service.
  * - `singleton`: One instance per container.

package/dist/unplugin/index.cjs

@@ -5,12 +5,25 @@ typescript = require_GraphValidator.__toESM(typescript);
 
 //#region src/generator/Generator.ts
 /**
-* Generates the TypeScript code for the dependency injection container.
+* Generates TypeScript code for the dependency injection container.
+*
+* Takes a validated dependency graph and produces:
+* - Import statements for all dependencies
+* - Factory functions for each service
+* - A NeoContainer class with resolve logic
 */
 var Generator = class {
+	/**
+	* Creates a new Generator.
+	* @param graph - The validated dependency graph to generate code from.
+	*/
 	constructor(graph) {
 		this.graph = graph;
 	}
+	/**
+	* Generates the complete container code as a string.
+	* @returns TypeScript source code for the generated container.
+	*/
 	generate() {
 		const sorted = this.topologicalSort();
 		const imports = /* @__PURE__ */ new Map();
@@ -147,6 +160,10 @@ export class NeoContainer {
 export const container = new NeoContainer(${containerArgs});
 `;
 	}
+	/**
+	* Sorts services in topological order (dependencies before dependents).
+	* @returns Array of TokenIds in dependency order.
+	*/
 	topologicalSort() {
 		const visited = /* @__PURE__ */ new Set();
 		const sorted = [];
@@ -162,6 +179,11 @@ export const container = new NeoContainer(${containerArgs});
 		for (const id of this.graph.nodes.keys()) visit(id);
 		return sorted;
 	}
+	/**
+	* Creates a valid JavaScript function name from a token ID.
+	* @param tokenId - The token identifier.
+	* @returns A sanitized factory function name.
+	*/
 	getFactoryName(tokenId) {
 		return `create_${tokenId.replace(/[^a-zA-Z0-9]/g, "_")}`;
 	}
@@ -170,21 +192,23 @@ export const container = new NeoContainer(${containerArgs});
 //#endregion
 //#region src/unplugin/index.ts
 /**
-* The Unplugin factory for Neo-Syringe.
+* Neo-Syringe build plugin for Vite, Rollup, Webpack, and other bundlers.
 *
-* This plugin integrates with Vite, Rollup, Webpack, etc.
-* It intercepts files containing `createContainer` calls, analyzes them,
-* and replaces the runtime configuration code with the generated dependency graph.
+* Intercepts files containing `defineBuilderConfig` calls, analyzes the
+* dependency graph, validates it, and replaces the configuration with
+* generated factory code.
 *
 * @example
+* ```typescript
 * // vite.config.ts
 * import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
 *
 * export default defineConfig({
-*   plugins: [neoSyringePlugin.vite()],
+*   plugins: [neoSyringePlugin.vite()]
 * });
+* ```
 */
-const neoSyringePlugin = (0, unplugin.createUnplugin)((_options) => {
+const neoSyringePlugin = (0, unplugin.createUnplugin)(() => {
 	return {
 		name: "neo-syringe-plugin",
 		transformInclude(id) {

package/dist/unplugin/index.d.cts

@@ -2,19 +2,21 @@ import * as unplugin0 from "unplugin";
 
 //#region src/unplugin/index.d.ts
 /**
- * The Unplugin factory for Neo-Syringe.
+ * Neo-Syringe build plugin for Vite, Rollup, Webpack, and other bundlers.
  *
- * This plugin integrates with Vite, Rollup, Webpack, etc.
- * It intercepts files containing `createContainer` calls, analyzes them,
- * and replaces the runtime configuration code with the generated dependency graph.
+ * Intercepts files containing `defineBuilderConfig` calls, analyzes the
+ * dependency graph, validates it, and replaces the configuration with
+ * generated factory code.
  *
  * @example
+ * ```typescript
  * // vite.config.ts
  * import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
  *
  * export default defineConfig({
- *   plugins: [neoSyringePlugin.vite()],
+ *   plugins: [neoSyringePlugin.vite()]
  * });
+ * ```
  */
 declare const neoSyringePlugin: unplugin0.UnpluginInstance<unknown, boolean>;
 //#endregion

package/dist/unplugin/index.d.mts

@@ -2,19 +2,21 @@ import * as unplugin0 from "unplugin";
 
 //#region src/unplugin/index.d.ts
 /**
- * The Unplugin factory for Neo-Syringe.
+ * Neo-Syringe build plugin for Vite, Rollup, Webpack, and other bundlers.
  *
- * This plugin integrates with Vite, Rollup, Webpack, etc.
- * It intercepts files containing `createContainer` calls, analyzes them,
- * and replaces the runtime configuration code with the generated dependency graph.
+ * Intercepts files containing `defineBuilderConfig` calls, analyzes the
+ * dependency graph, validates it, and replaces the configuration with
+ * generated factory code.
  *
  * @example
+ * ```typescript
  * // vite.config.ts
  * import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
  *
  * export default defineConfig({
- *   plugins: [neoSyringePlugin.vite()],
+ *   plugins: [neoSyringePlugin.vite()]
  * });
+ * ```
  */
 declare const neoSyringePlugin: unplugin0.UnpluginInstance<unknown, boolean>;
 //#endregion

package/dist/unplugin/index.mjs

@@ -4,12 +4,25 @@ import * as ts from "typescript";
 
 //#region src/generator/Generator.ts
 /**
-* Generates the TypeScript code for the dependency injection container.
+* Generates TypeScript code for the dependency injection container.
+*
+* Takes a validated dependency graph and produces:
+* - Import statements for all dependencies
+* - Factory functions for each service
+* - A NeoContainer class with resolve logic
 */
 var Generator = class {
+	/**
+	* Creates a new Generator.
+	* @param graph - The validated dependency graph to generate code from.
+	*/
 	constructor(graph) {
 		this.graph = graph;
 	}
+	/**
+	* Generates the complete container code as a string.
+	* @returns TypeScript source code for the generated container.
+	*/
 	generate() {
 		const sorted = this.topologicalSort();
 		const imports = /* @__PURE__ */ new Map();
@@ -146,6 +159,10 @@ export class NeoContainer {
 export const container = new NeoContainer(${containerArgs});
 `;
 	}
+	/**
+	* Sorts services in topological order (dependencies before dependents).
+	* @returns Array of TokenIds in dependency order.
+	*/
 	topologicalSort() {
 		const visited = /* @__PURE__ */ new Set();
 		const sorted = [];
@@ -161,6 +178,11 @@ export const container = new NeoContainer(${containerArgs});
 		for (const id of this.graph.nodes.keys()) visit(id);
 		return sorted;
 	}
+	/**
+	* Creates a valid JavaScript function name from a token ID.
+	* @param tokenId - The token identifier.
+	* @returns A sanitized factory function name.
+	*/
 	getFactoryName(tokenId) {
 		return `create_${tokenId.replace(/[^a-zA-Z0-9]/g, "_")}`;
 	}
@@ -169,21 +191,23 @@ export const container = new NeoContainer(${containerArgs});
 //#endregion
 //#region src/unplugin/index.ts
 /**
-* The Unplugin factory for Neo-Syringe.
+* Neo-Syringe build plugin for Vite, Rollup, Webpack, and other bundlers.
 *
-* This plugin integrates with Vite, Rollup, Webpack, etc.
-* It intercepts files containing `createContainer` calls, analyzes them,
-* and replaces the runtime configuration code with the generated dependency graph.
+* Intercepts files containing `defineBuilderConfig` calls, analyzes the
+* dependency graph, validates it, and replaces the configuration with
+* generated factory code.
 *
 * @example
+* ```typescript
 * // vite.config.ts
 * import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
 *
 * export default defineConfig({
-*   plugins: [neoSyringePlugin.vite()],
+*   plugins: [neoSyringePlugin.vite()]
 * });
+* ```
 */
-const neoSyringePlugin = createUnplugin((_options) => {
+const neoSyringePlugin = createUnplugin(() => {
 	return {
 		name: "neo-syringe-plugin",
 		transformInclude(id) {

package/docs/.vitepress/config.ts

@@ -0,0 +1,109 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Neo-Syringe',
+  description: 'Zero-Overhead, Compile-Time Dependency Injection for TypeScript',
+
+  head: [
+    ['link', { rel: 'icon', href: '/logo.png' }],
+    ['meta', { name: 'theme-color', content: '#0d9488' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:title', content: 'Neo-Syringe' }],
+    ['meta', { property: 'og:description', content: 'Zero-Overhead, Compile-Time Dependency Injection for TypeScript' }],
+    ['meta', { property: 'og:image', content: '/logo.png' }],
+  ],
+
+  base: '/neo-syringe/',
+
+  themeConfig: {
+    logo: '/logo.png',
+
+    nav: [
+      { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'API', link: '/api/types' },
+      {
+        text: 'Examples',
+        items: [
+          { text: 'Basic Usage', link: '/guide/basic-usage' },
+          { text: 'Parent Container', link: '/guide/parent-container' },
+          { text: 'Legacy Migration', link: '/guide/legacy-migration' },
+        ]
+      },
+      {
+        text: 'Links',
+        items: [
+          { text: 'GitHub', link: 'https://github.com/djodjonx/neo-syringe' },
+          { text: 'NPM', link: 'https://www.npmjs.com/package/@djodjonx/neo-syringe' },
+          { text: 'Changelog', link: 'https://github.com/djodjonx/neo-syringe/blob/main/CHANGELOG.md' },
+        ]
+      }
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Introduction',
+          items: [
+            { text: 'What is Neo-Syringe?', link: '/guide/what-is-neo-syringe' },
+            { text: 'Getting Started', link: '/guide/getting-started' },
+            { text: 'Why Neo-Syringe?', link: '/guide/why-neo-syringe' },
+          ]
+        },
+        {
+          text: 'Core Concepts',
+          items: [
+            { text: 'Basic Usage', link: '/guide/basic-usage' },
+            { text: 'Injection Types', link: '/guide/injection-types' },
+            { text: 'Lifecycle', link: '/guide/lifecycle' },
+            { text: 'Scoped Injections', link: '/guide/scoped-injections' },
+          ]
+        },
+        {
+          text: 'Advanced',
+          items: [
+            { text: 'Parent Container', link: '/guide/parent-container' },
+            { text: 'Legacy Migration', link: '/guide/legacy-migration' },
+            { text: 'Generated Code', link: '/guide/generated-code' },
+          ]
+        },
+        {
+          text: 'Tools',
+          items: [
+            { text: 'CLI Validator', link: '/guide/cli' },
+            { text: 'IDE Plugin', link: '/guide/ide-plugin' },
+          ]
+        }
+      ],
+      '/api/': [
+        {
+          text: 'API Reference',
+          items: [
+            { text: 'Types', link: '/api/types' },
+            { text: 'Functions', link: '/api/functions' },
+            { text: 'Configuration', link: '/api/configuration' },
+          ]
+        }
+      ]
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/djodjonx/neo-syringe' },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/@djodjonx/neo-syringe' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2024-present Neo-Syringe Contributors'
+    },
+
+    search: {
+      provider: 'local'
+    },
+
+    editLink: {
+      pattern: 'https://github.com/djodjonx/neo-syringe/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    }
+  }
+})
+

package/docs/.vitepress/theme/custom.css

@@ -0,0 +1,150 @@
+/**
+ * Neo-Syringe Custom Theme
+ * Colors: Teal (#0d9488) + Orange (#f97316)
+ */
+
+:root {
+  /* Brand Colors */
+  --neo-teal: #0d9488;
+  --neo-teal-light: #14b8a6;
+  --neo-teal-dark: #0f766e;
+  --neo-orange: #f97316;
+  --neo-orange-light: #fb923c;
+  --neo-orange-dark: #ea580c;
+
+  /* VitePress Color Overrides */
+  --vp-c-brand-1: var(--neo-teal);
+  --vp-c-brand-2: var(--neo-teal-light);
+  --vp-c-brand-3: var(--neo-teal-dark);
+  --vp-c-brand-soft: rgba(13, 148, 136, 0.14);
+
+  /* Accent for highlights */
+  --vp-c-tip-1: var(--neo-teal);
+  --vp-c-tip-2: var(--neo-teal-light);
+  --vp-c-tip-3: var(--neo-teal-dark);
+  --vp-c-tip-soft: rgba(13, 148, 136, 0.14);
+
+  /* Warning with orange */
+  --vp-c-warning-1: var(--neo-orange);
+  --vp-c-warning-2: var(--neo-orange-light);
+  --vp-c-warning-3: var(--neo-orange-dark);
+  --vp-c-warning-soft: rgba(249, 115, 22, 0.14);
+
+  /* Button colors */
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: #fff;
+  --vp-button-brand-bg: var(--neo-teal);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: #fff;
+  --vp-button-brand-hover-bg: var(--neo-teal-light);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: #fff;
+  --vp-button-brand-active-bg: var(--neo-teal-dark);
+
+  /* Alt button with orange accent */
+  --vp-button-alt-border: var(--neo-orange);
+  --vp-button-alt-text: var(--neo-orange);
+  --vp-button-alt-bg: transparent;
+  --vp-button-alt-hover-border: var(--neo-orange-light);
+  --vp-button-alt-hover-text: var(--neo-orange-light);
+  --vp-button-alt-hover-bg: rgba(249, 115, 22, 0.1);
+
+  /* Home hero gradient */
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(135deg, var(--neo-teal) 0%, var(--neo-orange) 100%);
+
+  --vp-home-hero-image-background-image: linear-gradient(135deg, rgba(13, 148, 136, 0.3) 0%, rgba(249, 115, 22, 0.3) 100%);
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+.dark {
+  --vp-c-brand-1: var(--neo-teal-light);
+  --vp-c-brand-2: var(--neo-teal);
+  --vp-c-brand-3: var(--neo-teal-dark);
+
+  --vp-home-hero-image-background-image: linear-gradient(135deg, rgba(13, 148, 136, 0.4) 0%, rgba(249, 115, 22, 0.4) 100%);
+}
+
+/* Hero section enhancements */
+.VPHero .VPImage {
+  max-width: 280px;
+  max-height: 280px;
+}
+
+.VPHero .tagline {
+  font-size: 1.25rem !important;
+  color: var(--vp-c-text-2);
+}
+
+/* Feature cards */
+.VPFeature {
+  border: 1px solid var(--vp-c-divider);
+  transition: all 0.3s ease;
+}
+
+.VPFeature:hover {
+  border-color: var(--neo-teal);
+  box-shadow: 0 4px 20px rgba(13, 148, 136, 0.15);
+}
+
+.VPFeature .icon {
+  font-size: 2rem;
+}
+
+/* Code blocks */
+.vp-code-group .tabs label.active {
+  color: var(--neo-teal);
+}
+
+/* Custom badges */
+.vp-badge.tip {
+  background-color: var(--neo-teal);
+}
+
+.vp-badge.warning {
+  background-color: var(--neo-orange);
+}
+
+/* Navigation active state */
+.VPNavBarMenuLink.active,
+.VPSidebarItem.is-active > .item > .link > .text {
+  color: var(--neo-teal) !important;
+}
+
+/* Custom container styles */
+.custom-block.tip {
+  border-color: var(--neo-teal);
+}
+
+.custom-block.warning {
+  border-color: var(--neo-orange);
+}
+
+/* Table styling */
+table {
+  border-collapse: collapse;
+  width: 100%;
+}
+
+th {
+  background-color: rgba(13, 148, 136, 0.1);
+}
+
+/* Gradient text utility */
+.gradient-text {
+  background: linear-gradient(135deg, var(--neo-teal) 0%, var(--neo-orange) 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+/* Animation for hero */
+@keyframes float {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-10px); }
+}
+
+.VPHero .VPImage img {
+  animation: float 3s ease-in-out infinite;
+}
+

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Customize VitePress theme with Neo-Syringe colors
+ * Primary: Teal/Cyan (#0d9488)
+ * Accent: Orange (#f97316)
+ */
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {})
+  },
+} satisfies Theme
+