@thomasrepnik/ts-implscan 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Repnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,293 @@
-# Temporary Holding Version
+# ts-implscan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@thomasrepnik/ts-implscan)](https://www.npmjs.com/package/@thomasrepnik/ts-implscan)
+[![CI](https://github.com/thomasrepnik/ts-implscan/actions/workflows/ci.yml/badge.svg)](https://github.com/thomasrepnik/ts-implscan/actions/workflows/ci.yml)
+
+**Spring-style `List<A>` injection for TypeScript.** Find every `implements A` and generate the registry.
+
+## Installation
+
+```sh
+npm install --save-dev @thomasrepnik/ts-implscan
+```
+
+The package contains two things:
+
+| What | How you use it |
+|---|---|
+| The `ImplScan` marker interface | `import type { ImplScan } from '@thomasrepnik/ts-implscan'` |
+| The `ts-implscan` CLI (the generator) | `npx ts-implscan`, or in a `package.json` script |
+
+It's a dev dependency because it only runs at build time. The `ImplScan` import is type-only and
+disappears when compiled, so nothing from this package ends up in your production bundle.
+You need Node 22 or newer.
+
+## Quick start
+
+### 1. Mark an interface
+
+Extend `ImplScan` to tell the generator to collect the interface's implementations:
+
+```ts
+// payment-handler.ts
+import type { ImplScan } from '@thomasrepnik/ts-implscan';
+
+export interface PaymentHandler extends ImplScan {
+  name: string;
+  pay(amount: number): string;
+}
+```
+
+### 2. Implement it
+
+Write implementations as usual, anywhere under `src/`. They must be exported:
+
+```ts
+// card-handler.ts
+export class CardHandler implements PaymentHandler {
+  name = 'card';
+  pay(amount: number) {
+    return `charged ${amount} to credit card`;
+  }
+}
+
+// paypal-handler.ts
+export class PaypalHandler implements PaymentHandler { ... }
+```
+
+### 3. Generate the registry and use it
+
+Pick the variant for your project.
+
+#### With Angular
+
+Add the generator to your scripts, so it runs before every `ng serve` and `ng build`:
+
+```json
+"scripts": {
+  "generate": "ts-implscan --target angular --project tsconfig.app.json --out src/app/generated/implscan-registry.ts",
+  "prestart": "npm run generate",
+  "prebuild": "npm run generate"
+}
+```
+
+Register all implementations once:
+
+```ts
+// app.config.ts
+import { provideImplscan } from './generated/implscan-registry';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideImplscan()],
+};
+```
+
+Inject the list anywhere. This is the equivalent of Spring's `List<PaymentHandler>`:
+
+```ts
+import { PAYMENT_HANDLER_LIST } from './generated/implscan-registry';
+
+@Injectable({ providedIn: 'root' })
+export class PaymentService {
+  private readonly handlers = inject(PAYMENT_HANDLER_LIST); // PaymentHandler[]
+
+  payWithAll(amount: number) {
+    return this.handlers.map((handler) => handler.pay(amount));
+  }
+}
+```
+
+Implementations can use DI themselves, for example `private readonly http = inject(HttpClient)`.
+Mark them with `@Injectable()`, but **without** `providedIn: 'root'`. `provideImplscan()` already
+creates one instance per implementation, so a root-provided implementation would exist twice.
+
+<details>
+<summary>What gets generated</summary>
+
+```ts
+// src/app/generated/implscan-registry.ts
+// GENERATED by ts-implscan – do not edit
+import { InjectionToken, type Provider } from '@angular/core';
+import type { PaymentHandler } from '../payment/payment-handler';
+import { CardHandler } from '../payment/card-handler';
+import { PaypalHandler } from '../payment/paypal-handler';
+
+export const PaymentHandlerImplementations: Array<new (...args: any[]) => PaymentHandler> = [CardHandler, PaypalHandler];
+export const PAYMENT_HANDLER_LIST = new InjectionToken<PaymentHandler[]>('PAYMENT_HANDLER_LIST');
+
+export function provideImplscan(): Provider[] {
+  return [
+    { provide: PAYMENT_HANDLER_LIST, useClass: CardHandler, multi: true },
+    { provide: PAYMENT_HANDLER_LIST, useClass: PaypalHandler, multi: true },
+  ];
+}
+```
+
+There is one token per marked interface, and `provideImplscan()` registers all of them.
+</details>
+
+The [example](example/main-angular.ts) in this repository resolves the generated providers
+through Angular's real injector (`npm run start:angular`).
+
+#### Without Angular
+
+The default target generates plain arrays of classes, with no framework dependency. It works for
+Node, other frameworks, or plain TypeScript:
+
+```json
+"scripts": {
+  "generate": "ts-implscan",
+  "prestart": "npm run generate",
+  "prebuild": "npm run generate"
+}
+```
+
+```ts
+import { PaymentHandlerImplementations } from './generated/implscan-registry';
+
+const handlers = PaymentHandlerImplementations.map((Handler) => new Handler()); // PaymentHandler[]
+
+for (const handler of handlers) {
+  console.log(handler.pay(42));
+}
+```
+
+If your implementations have dependencies, register the classes from the array with your DI
+container instead of calling `new`.
+
+<details>
+<summary>What gets generated</summary>
+
+```ts
+// src/generated/implscan-registry.ts
+// GENERATED by ts-implscan – do not edit
+import type { PaymentHandler } from '../payment/payment-handler';
+import { CardHandler } from '../payment/card-handler';
+import { PaypalHandler } from '../payment/paypal-handler';
+
+export const PaymentHandlerImplementations: Array<new (...args: any[]) => PaymentHandler> = [CardHandler, PaypalHandler];
+```
+</details>
+
+The [example](example/main.ts) in this repository does exactly this (`npm start`).
+
+**That's it.** A new implementation is picked up the next time the generator runs. A new
+interface only needs `extends ImplScan`, and with Angular its token is generated too.
+
+## Good to know
+
+- **Check what would be collected** without writing anything: `npx ts-implscan --dry-run`.
+- **Replace a whole list in Angular tests** with one provider:
+  `providers: [{ provide: PAYMENT_HANDLER_LIST, useValue: [fakeHandler] }]`.
+- **A marked interface without implementations** gives an empty array, and in Angular a
+  `useValue: []` provider, so injecting it doesn't throw.
+- **Commit the generated file**, so the IDE and type checks work right after a checkout. Let CI
+  catch a forgotten regeneration with `npm run generate && git diff --exit-code`.
+- **In CI**, `prebuild` only runs through `npm run build`. If your pipeline calls `ng build`
+  directly, run `npm run generate` first.
+
+## Why
+
+In Spring you can inject `List<PaymentHandler>`, and the container hands you every bean that
+implements the interface. TypeScript can't do this out of the box, for two reasons:
+
+1. **Interfaces are erased.** At runtime nothing records that a class implements `PaymentHandler`.
+2. **There is no classpath scanning.** JavaScript only runs files that something imports, so a
+   new implementation that nobody imports doesn't exist at runtime.
+
+DI containers such as Angular, tsyringe or InversifyJS solve this with injection tokens, but
+then you have to register every implementation by hand, and it's easy to forget one.
+
+`ts-implscan` moves the scan to build time. It uses [ts-morph](https://ts-morph.com) and the
+TypeScript type checker to find every exported class that `implements` a marked interface. The
+generated file is ordinary TypeScript, so `tsc` fails if a listed class doesn't actually satisfy
+its interface.
+
+**Why a marker interface rather than a comment tag like `/** @implscan */`?** The marker is
+checked by the compiler, so a typo doesn't silently drop the interface. Your IDE's "Find usages"
+on `ImplScan` lists every collected interface, and renames are safe. It's the same idea as a Java
+marker interface such as `Serializable`, and it keeps out the interfaces you implement for other
+reasons, such as Angular's `OnInit`.
+
+## When it's helpful
+
+- **Plugin and strategy patterns**, such as payment providers, exporters, validators, notification
+  channels or feature handlers, where the set of implementations keeps growing.
+- **Teams coming from Spring or Java** who want the open/closed principle that `List<A>` injection
+  gives them: adding behaviour means adding a class, not editing a central list.
+- **Angular apps** with many multi-provider tokens, so nobody forgets to register a new
+  implementation, or to write the token.
+
+It's probably overkill if you have two implementations that rarely change. A hand-written array
+is fine then.
+
+## CLI options
+
+```sh
+ts-implscan [--project tsconfig.json] [--src src] [--out src/generated/implscan-registry.ts] [--target plain|angular] [--dry-run]
+```
+
+| Option       | Default                              | Meaning                                                  |
+|--------------|--------------------------------------|----------------------------------------------------------|
+| `--project`  | `tsconfig.json`                      | tsconfig to read compiler options from (paths, resolution) |
+| `--src`      | `src`                                | Folder to scan. `*.spec.ts` and `*.d.ts` are skipped.      |
+| `--out`      | `src/generated/implscan-registry.ts` | File to generate                                         |
+| `--target`   | `plain`                              | `angular` adds an `InjectionToken` per interface and `provideImplscan()` |
+| `--dry-run`  | off                                  | Print the result to stdout instead of writing it         |
+| `-h, --help` |                                      | Show the help                                            |
+
+The files to scan come from `--src`, not from the tsconfig, because a new implementation isn't
+imported anywhere yet. The tsconfig is only read for compiler options. The import extension in
+the generated file follows it too: `.ts` with `allowImportingTsExtensions`, `.js` with `NodeNext`,
+and no extension with `bundler`, which is what Angular uses.
+
+## Limits
+
+- Only interfaces that extend `ImplScan` **directly** are collected. The CLI detects the marker by
+  its name, so a local `interface ImplScan {}` works too.
+- Only explicit `implements X` clauses count. Classes that only match the interface structurally,
+  and subclasses of an implementing class, are not found.
+- Implementations must be exported, non-abstract, named-export classes. A non-exported
+  implementation is skipped with a warning.
+
+## Development
+
+This repository contains the library in `src/` and a runnable demo in `example/`. The demo has
+two marked interfaces, `PaymentHandler` and `Notifier`.
+
+```sh
+npm install
+npm run generate:dry           # print the plain registry for the example, write nothing
+npm run generate:dry:angular   # the same with Angular tokens and providers
+npm start                      # regenerate, then run the example with plain arrays
+npm run start:angular          # regenerate, then resolve everything through Angular's real Injector
+npm run typecheck
+npm run test:package           # pack, install into an empty project, run the CLI from there
+```
+
+`@angular/core` and `rxjs` are dev dependencies only so that `start:angular` can run Angular's
+injector in Node. The published package only depends on `ts-morph`.
+
+### Releasing
+
+Releases are uploaded to npm by `.github/workflows/release.yml`, using npm
+[trusted publishing](https://docs.npmjs.com/trusted-publishers). It doesn't need an npm token.
+
+```sh
+npm version minor            # or patch / major: bumps package.json, commits and tags vX.Y.Z
+git push --follow-tags
+gh release create v0.2.0 --generate-notes   # or click "Publish release" on GitHub
+```
+
+Publishing the GitHub release starts the workflow. It checks that the tag matches
+`package.json`, type-checks, runs the package smoke test and **stages** the version on npm.
+A staged version isn't public until a maintainer approves it with 2FA:
+
+```sh
+npm stage list @thomasrepnik/ts-implscan   # shows the stage id
+npm stage approve <stage-id>
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Build-time "component scan": finds every exported interface that extends the
+// `ImplScan` marker, then every exported class that implements one of them, and
+// writes one array of implementations per interface. With `--target angular` it
+// also writes an InjectionToken per interface and `provideImplscan()`.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { Node, Project, ts } from 'ts-morph';
+const MARKER = 'ImplScan';
+const { values: args } = parseArgs({
+    options: {
+        project: { type: 'string', default: 'tsconfig.json' },
+        src: { type: 'string', default: 'src' },
+        out: { type: 'string', default: 'src/generated/implscan-registry.ts' },
+        target: { type: 'string', default: 'plain' },
+        'dry-run': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+    },
+});
+if (args.help) {
+    console.log(`Usage: ts-implscan [options]
+
+  --project <file>   tsconfig to read compiler options from
+                     (default: tsconfig.json)
+  --src <dir>        folder to scan (default: src)
+  --out <file>       file to generate
+                     (default: src/generated/implscan-registry.ts)
+  --target <target>  plain | angular (default: plain)
+  --dry-run          print the result instead of writing it
+  -h, --help         show this help`);
+    process.exit(0);
+}
+if (args.target !== 'plain' && args.target !== 'angular') {
+    console.error(`unknown --target '${args.target}', expected 'plain' or 'angular'`);
+    process.exit(1);
+}
+const outFile = path.resolve(args.out);
+const outDir = path.dirname(outFile);
+// Use the tsconfig only for compiler options (paths, module resolution). Files come from
+// a glob, because new implementations are not imported anywhere yet (Angular's
+// tsconfig.app.json only lists main.ts).
+const project = new Project({ tsConfigFilePath: args.project, skipAddingFilesFromTsConfig: true });
+project.addSourceFilesAtPaths([`${args.src}/**/*.ts`, `!${args.src}/**/*.spec.ts`, `!${args.src}/**/*.d.ts`]);
+const sourceFiles = project.getSourceFiles().filter((f) => f.getFilePath() !== outFile);
+// Pick the import extension the tsconfig expects: `.ts` (Node type stripping),
+// `.js` (NodeNext) or none (Angular's `bundler` resolution).
+const options = project.getCompilerOptions();
+const importExt = options.allowImportingTsExtensions
+    ? '.ts'
+    : options.moduleResolution === ts.ModuleResolutionKind.Node16 ||
+        options.moduleResolution === ts.ModuleResolutionKind.NodeNext
+        ? '.js'
+        : '';
+// resolve through the type checker so aliased/renamed imports still match
+function resolveInterface(clause) {
+    let symbol = clause.getExpression().getSymbol();
+    if (symbol?.isAlias())
+        symbol = symbol.getAliasedSymbol();
+    return symbol?.getDeclarations().find(Node.isInterfaceDeclaration);
+}
+const keyOf = (decl) => `${decl.getSourceFile().getFilePath()}#${decl.getName()}`;
+const registry = new Map();
+// 1. interfaces that opt in by extending the marker directly
+for (const sourceFile of sourceFiles) {
+    for (const iface of sourceFile.getInterfaces()) {
+        if (!iface.isExported())
+            continue;
+        if (!iface.getExtends().some((clause) => resolveInterface(clause)?.getName() === MARKER))
+            continue;
+        registry.set(keyOf(iface), { iface: { name: iface.getName(), file: sourceFile.getFilePath() }, impls: [] });
+    }
+}
+// 2. classes implementing one of those interfaces
+for (const sourceFile of sourceFiles) {
+    for (const cls of sourceFile.getClasses()) {
+        const name = cls.getName();
+        if (!name || cls.isAbstract())
+            continue;
+        for (const clause of cls.getImplements()) {
+            const decl = resolveInterface(clause);
+            const entry = decl && registry.get(keyOf(decl));
+            if (!entry)
+                continue;
+            if (!cls.isExported() || cls.isDefaultExport()) {
+                console.warn(`skipped ${name} (${path.relative(process.cwd(), sourceFile.getFilePath())}): needs a named export`);
+                continue;
+            }
+            entry.impls.push({ name, file: sourceFile.getFilePath() });
+        }
+    }
+}
+function importPath(file) {
+    const rel = path.relative(outDir, file).split(path.sep).join('/').replace(/\.ts$/, importExt);
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+// PaymentHandler -> PAYMENT_HANDLER_LIST
+function tokenName(interfaceName) {
+    const snake = interfaceName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/([A-Z])([A-Z][a-z])/g, '$1_$2');
+    return `${snake.toUpperCase()}_LIST`;
+}
+const angular = args.target === 'angular';
+const imports = angular ? [`import { InjectionToken, type Provider } from '@angular/core';`] : [];
+const exports = [];
+const providers = [];
+const entries = [...registry.values()].sort((a, b) => a.iface.name.localeCompare(b.iface.name));
+for (const { iface, impls } of entries) {
+    impls.sort((a, b) => a.name.localeCompare(b.name));
+    imports.push(`import type { ${iface.name} } from '${importPath(iface.file)}';`);
+    for (const impl of impls)
+        imports.push(`import { ${impl.name} } from '${importPath(impl.file)}';`);
+    // same shape as Angular's Type<T>, so it can be used directly as `useClass`
+    exports.push(`export const ${iface.name}Implementations: Array<new (...args: any[]) => ${iface.name}> = [${impls.map((i) => i.name).join(', ')}];`);
+    if (angular) {
+        const token = tokenName(iface.name);
+        exports.push(`export const ${token} = new InjectionToken<${iface.name}[]>('${token}');`);
+        // a multi token without any provider would throw on inject(), so fall back to []
+        if (impls.length === 0)
+            providers.push(`    { provide: ${token}, useValue: [] },`);
+        for (const impl of impls)
+            providers.push(`    { provide: ${token}, useClass: ${impl.name}, multi: true },`);
+    }
+}
+if (angular) {
+    exports.push('', 'export function provideImplscan(): Provider[] {', '  return [', ...providers, '  ];', '}');
+}
+const content = ['// GENERATED by ts-implscan – do not edit', ...imports, '', ...exports, ''].join('\n');
+if (args['dry-run']) {
+    console.log(content);
+}
+else {
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(outFile, content);
+    for (const { iface, impls } of entries)
+        console.log(`${iface.name}: ${impls.map((i) => i.name).join(', ') || '(none)'}`);
+    console.log(`wrote ${path.relative(process.cwd(), outFile)}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Marker interface: every interface that extends `ImplScan` gets its implementations
+ * collected by the `ts-implscan` CLI. It has no members and no runtime cost.
+ *
+ * @example
+ * export interface PaymentHandler extends ImplScan {
+ *   pay(amount: number): string;
+ * }
+ */
+export interface ImplScan {
+}

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@thomasrepnik/ts-implscan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Spring-style List<A> injection for TypeScript: find every class implementing a marked interface and generate a typed registry, plus Angular InjectionTokens and providers.",
+  "keywords": [
+    "typescript",
+    "dependency-injection",
+    "angular",
+    "multi-provider",
+    "injection-token",
+    "code-generation",
+    "ts-morph",
+    "spring",
+    "component-scan"
+  ],
+  "homepage": "https://github.com/thomasrepnik/ts-implscan#readme",
+  "bugs": {
+    "url": "https://github.com/thomasrepnik/ts-implscan/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomasrepnik/ts-implscan.git"
+  },
+  "license": "MIT",
+  "author": "Thomas Repnik",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ts-implscan": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "generate": "node src/cli.ts --src example --out example/generated/implscan-registry.ts && node src/cli.ts --src example --target angular --out example/generated/implscan-registry.angular.ts",
+    "generate:dry": "node src/cli.ts --src example --dry-run",
+    "generate:dry:angular": "node src/cli.ts --src example --target angular --dry-run",
+    "prestart": "npm run generate",
+    "start": "node example/main.ts",
+    "prestart:angular": "npm run generate",
+    "start:angular": "node example/main-angular.ts",
+    "test:package": "bash scripts/smoke-test.sh"
+  },
+  "dependencies": {
+    "ts-morph": "^28.0.0"
+  },
+  "devDependencies": {
+    "@angular/core": "^22.2.4",
+    "@types/node": "^26.6.6",
+    "rxjs": "^7.8.2",
+    "typescript": "^7.0.2"
+  }
+}