navi-di 0.1.0 → 1.0.0

package/CONTRIBUTING.md

@@ -17,11 +17,13 @@ This repository is focused on a small, explicit DI core for standard ECMAScript
 This repository uses Lefthook.
 
 - `pre-commit` runs fast staged-file checks for lint and formatting.
+- hooks are contributor-local and are not installed for package consumers.
 
-If hooks stop working locally, reinstall them with `bun run hooks:install`.
+Install or reinstall them locally with `bun run hooks:install`.
 
 ## Pull request checklist
 
+- PR CI runs lint, format, typecheck, test, and build checks automatically.
 - the change is focused and documented;
 - scripts in the local checks section pass;
 - package exports and Node compatibility were kept intact;

package/README.md

@@ -46,11 +46,17 @@ No environment variables or external services are required for local development
 
 ## Public entry points
 
-The package root currently exports:
+The package root currently exports runtime values and TypeScript types.
+
+Runtime exports:
 
 - `Container`
 - `Service`
 - `Inject`
+- `Token`
+
+Type-only exports:
+
 - `Constructable` / `AbstractConstructable`
 - `ServiceIdentifier`
 
@@ -126,10 +132,16 @@ Current behavior:
 
 ## Decorators
 
-### `@Service(options?)`
+### `@Service(idOrOptions?)`
 
 Registers a class in the default container.
 
+Accepted forms today:
+
+- `@Service()`
+- `@Service(id)`
+- `@Service({ id, scope })`
+
 Options supported today:
 
 - `id?: ServiceIdentifier`
@@ -146,7 +158,8 @@ class LoggerService {}
 const logger = Container.of().get('logger');
 ```
 
-Note: a custom string id works for manual resolution through `container.get(...)`, but `@Inject()` currently accepts a constructable class dependency rather than an arbitrary token.
+Custom identifiers work for both `container.get(...)` and `@Inject(...)`.
+When you use `Token` instances, resolution is based on object identity, so create the token once and reuse the same instance everywhere.
 
 ### `@Inject(dependency)`
 
@@ -161,6 +174,35 @@ Current characteristics:
 - injected fields are defined as writable and configurable own properties on the created instance;
 - injected fields are assigned after construction, so they are not available inside constructors or field initializers.
 
+Token example:
+
+```ts
+import { Container, Inject, Service, Token } from 'navi-di';
+
+interface Logger {
+  log(message: string): void;
+}
+
+const LOGGER = new Token<Logger>('Logger');
+
+@Service(LOGGER)
+class ConsoleLogger implements Logger {
+  public log(message: string) {
+    console.log(message);
+  }
+}
+
+@Service()
+class HandlerService {
+  @Inject(LOGGER)
+  public logger!: Logger;
+}
+
+const handler = Container.of().get(HandlerService);
+
+handler.logger.log('hello from token injection');
+```
+
 ## Container API
 
 ### `Container.of(id?)`
@@ -193,6 +235,13 @@ Supported strategies:
 
 This is especially useful in tests.
 
+### `container.set(metadata)`
+
+Registers or replaces service metadata for a service identifier.
+
+This is a low-level API that powers manual registration scenarios and internal tests.
+For application-facing code, prefer `@Service()` unless you specifically need to construct metadata yourself.
+
 ## Internal architecture
 
 The implementation is intentionally small and split into a few focused modules:
@@ -242,9 +291,9 @@ What they do:
 - `lint`: run `oxlint` with warnings denied
 - `fmt`: format the repository with `oxfmt`
 - `fmt:check`: verify formatting without writing changes
-- `hooks:*`: install, validate, or run the Lefthook-based Git hooks
+- `hooks:*`: install, validate, or run the repo-local Lefthook Git hooks
 
-`bun install` also triggers `postinstall`, which installs the local Git hooks automatically.
+Git hooks are optional and repo-local. After cloning, contributors can install them with `bun run hooks:install`.
 
 Current note: `typecheck` uses `tsconfig.json` with `noEmit: true`, while `build` uses `tsconfig.build.json` with `noEmit: false` to emit `dist/` and declaration files.
 
@@ -255,7 +304,8 @@ The repository currently enforces:
 - strict TypeScript checking;
 - `oxlint` for linting;
 - `oxfmt` for formatting;
-- Lefthook `pre-commit` checks for staged TypeScript, JavaScript, Markdown, YAML, and YML files.
+- PR CI checks for lint, format, typecheck, tests, and build;
+- optional Lefthook `pre-commit` checks for staged TypeScript, JavaScript, Markdown, YAML, and YML files.
 
 The package `prepack` script runs lint, format check, typecheck, and build before publishing.
 

package/dist/decorators/inject.d.ts

@@ -1,2 +1,2 @@
-import { type Constructable } from '../types';
-export declare function Inject<T>(dependency: Constructable<T>): (_: undefined, context: ClassFieldDecoratorContext) => void;
+import { type ServiceIdentifier } from '../types';
+export declare function Inject<T>(dependency: ServiceIdentifier<T>): (_: undefined, context: ClassFieldDecoratorContext) => void;

package/dist/decorators/service.d.ts

@@ -1,3 +1,4 @@
-import type { ServiceOption } from '../types';
+import type { ServiceIdentifier, ServiceOption } from '../types';
 export declare function Service(): Function;
+export declare function Service(id: ServiceIdentifier): Function;
 export declare function Service(options?: ServiceOption): Function;

package/dist/decorators/service.js

@@ -1,7 +1,17 @@
 import { ContainerRegistry } from '../container/registry';
 import { INJECTION_KEY, EMPTY_VALUE } from '../types';
-export function Service(options) {
+function normalizeArguments(args) {
+    if (!args) {
+        return {};
+    }
+    if (typeof args === 'object' && ('scope' in args || 'id' in args)) {
+        return args;
+    }
+    return { id: args };
+}
+export function Service(idOrOptions) {
     return function (target, context) {
+        const options = normalizeArguments(idOrOptions);
         const injections = (context.metadata[INJECTION_KEY] ?? []);
         ContainerRegistry.defaultContainer.set({
             id: options?.id ?? target,

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { Container } from './container';
 export { Service, Inject } from './decorators';
+export { Token } from './tokens';
 export type { AbstractConstructable, Constructable } from './types/constructable.ts';
 export type { ServiceIdentifier } from './types/service.ts';

package/dist/index.js

@@ -1,2 +1,3 @@
 export { Container } from './container';
 export { Service, Inject } from './decorators';
+export { Token } from './tokens';

package/dist/tokens/index.d.ts

@@ -0,0 +1 @@
+export { Token } from './token';

package/dist/tokens/index.js

@@ -0,0 +1 @@
+export { Token } from './token';

package/dist/tokens/token.d.ts

@@ -0,0 +1,5 @@
+export declare class Token<T> {
+    name?: string;
+    constructor(name?: string);
+    toString(): string;
+}

package/dist/tokens/token.js

@@ -0,0 +1,10 @@
+// oxlint-disable-next-line no-unused-vars
+export class Token {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    toString() {
+        return this.name ? `Token(${this.name})` : `Token()`;
+    }
+}

package/dist/types/service.d.ts

@@ -1,5 +1,6 @@
+import type { Token } from '../tokens';
 import type { AbstractConstructable, Constructable } from './constructable';
-export type ServiceIdentifier<T = unknown, Args extends unknown[] = never[]> = Constructable<T, Args> | AbstractConstructable<T, Args> | CallableFunction | string;
+export type ServiceIdentifier<T = unknown, Args extends unknown[] = never[]> = Constructable<T, Args> | AbstractConstructable<T, Args> | CallableFunction | string | Token<T>;
 export type ServiceScope = 'singleton' | 'container' | 'transient';
 export interface ServiceOption {
     id?: ServiceIdentifier;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "navi-di",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Dependency injection for standard ECMAScript decorators.",
+  "author": "naviary-sanctuary",
   "keywords": [
     "bun",
     "decorators",
@@ -51,7 +52,6 @@
     "lint": "oxlint . --deny-warnings",
     "fmt": "oxfmt --config .oxfmt.json .",
     "fmt:check": "oxfmt --check --config .oxfmt.json .",
-    "postinstall": "lefthook install",
     "prepack": "bun run lint && bun run fmt:check && bun run typecheck && bun run build",
     "test": "bun test --pass-with-no-tests"
   },