@djodjonx/neo-syringe 1.1.5 → 1.2.2

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
+

package/docs/api/configuration.md

@@ -0,0 +1,274 @@
+# Configuration
+
+Configure Neo-Syringe in your project.
+
+## Build Plugin
+
+### Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+export default defineConfig({
+  plugins: [neoSyringePlugin.vite()]
+});
+```
+
+### Rollup
+
+```typescript
+// rollup.config.js
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+
+export default {
+  input: 'src/main.ts',
+  output: {
+    file: 'dist/bundle.js',
+    format: 'esm'
+  },
+  plugins: [neoSyringePlugin.rollup()]
+};
+```
+
+### Webpack
+
+```javascript
+// webpack.config.js
+const { webpack } = require('@djodjonx/neo-syringe/plugin');
+
+module.exports = {
+  plugins: [webpack()]
+};
+```
+
+### esbuild
+
+```typescript
+// esbuild.config.js
+import { neoSyringePlugin } from '@djodjonx/neo-syringe/plugin';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+  entryPoints: ['src/main.ts'],
+  bundle: true,
+  outfile: 'dist/bundle.js',
+  plugins: [neoSyringePlugin.esbuild()]
+});
+```
+
+### Rspack
+
+```javascript
+// rspack.config.js
+const { rspack } = require('@djodjonx/neo-syringe/plugin');
+
+module.exports = {
+  plugins: [rspack()]
+};
+```
+
+## TypeScript LSP Plugin
+
+Add to `tsconfig.json` for IDE error detection:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      { "name": "@djodjonx/neo-syringe/lsp" }
+    ]
+  }
+}
+```
+
+::: tip VS Code
+Remember to select "Use Workspace Version" for TypeScript.
+:::
+
+## BuilderConfig Options
+
+```typescript
+defineBuilderConfig({
+  // Container name (for debugging)
+  name: 'AppContainer',
+  
+  // List of injections
+  injections: [
+    { token: UserService },
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ],
+  
+  // Inherit from partial configs
+  extends: [loggingPartial, databasePartial],
+  
+  // Parent container (Neo-Syringe or legacy)
+  useContainer: parentContainer
+});
+```
+
+### name
+
+Type: `string`
+
+Optional. The container name appears in error messages.
+
+```typescript
+defineBuilderConfig({
+  name: 'UserModule'
+});
+
+// Error: [UserModule] Service not found: XYZ
+```
+
+### injections
+
+Type: `Injection[]`
+
+Required. List of services to register.
+
+```typescript
+defineBuilderConfig({
+  injections: [
+    // Class autowiring
+    { token: UserService },
+    
+    // Interface binding
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    
+    // Explicit provider
+    { token: BaseService, provider: ConcreteService },
+    
+    // Factory
+    { token: useInterface<IConfig>(), provider: () => loadConfig() },
+    
+    // Property token
+    { token: useProperty<string>(ApiService, 'apiUrl'), provider: () => 'http://...' },
+    
+    // With lifecycle
+    { token: RequestContext, lifecycle: 'transient' },
+    
+    // Scoped override
+    { token: useInterface<ILogger>(), provider: MockLogger, scoped: true }
+  ]
+});
+```
+
+### extends
+
+Type: `PartialConfig[]`
+
+Optional. Inherit injections from partial configs.
+
+```typescript
+const loggingPartial = definePartialConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+defineBuilderConfig({
+  extends: [loggingPartial],
+  injections: [
+    { token: UserService }  // Can use ILogger
+  ]
+});
+```
+
+### useContainer
+
+Type: `Container | any`
+
+Optional. Parent container for delegation.
+
+```typescript
+// Neo-Syringe parent
+defineBuilderConfig({
+  useContainer: sharedKernel,
+  injections: [...]
+});
+
+// Legacy container (tsyringe, etc.)
+const legacy = declareContainerTokens<{...}>(tsyringeContainer);
+defineBuilderConfig({
+  useContainer: legacy,
+  injections: [...]
+});
+```
+
+## Injection Options
+
+```typescript
+interface Injection<T> {
+  token: Token<T>;
+  provider?: Provider<T>;
+  useFactory?: boolean;
+  lifecycle?: 'singleton' | 'transient';
+  scoped?: boolean;
+}
+```
+
+### token
+
+Type: `Token<T>` (required)
+
+What to register. Can be:
+
+- Class constructor: `UserService`
+- Interface token: `useInterface<ILogger>()`
+- Property token: `useProperty<string>(ApiService, 'apiUrl')`
+
+### provider
+
+Type: `Provider<T>`
+
+What provides the instance. Can be:
+
+- Class constructor: `ConsoleLogger`
+- Factory function: `(container) => new Service()`
+
+If omitted, the token itself is used (autowiring).
+
+### useFactory
+
+Type: `boolean`
+
+Force treating the provider as a factory function.
+
+```typescript
+// Auto-detected (arrow function)
+{ provider: () => createService() }
+
+// Explicit (regular function)
+{ provider: createService, useFactory: true }
+```
+
+### lifecycle
+
+Type: `'singleton' | 'transient'`
+
+Default: `'singleton'`
+
+How instances are managed.
+
+```typescript
+{ token: UserService, lifecycle: 'singleton' }  // One instance
+{ token: RequestContext, lifecycle: 'transient' }  // New each time
+```
+
+### scoped
+
+Type: `boolean`
+
+Default: `false`
+
+If `true`, resolve locally instead of delegating to parent.
+
+```typescript
+// Override parent's ILogger with local MockLogger
+{ token: useInterface<ILogger>(), provider: MockLogger, scoped: true }
+```
+
+See [Scoped Injections](/guide/scoped-injections) for details.
+