@ts-ioc-container/bundler 1.1.0 → 1.2.0

package/AGENTS.md

@@ -13,8 +13,11 @@ it.
 - A namespace is a folder: relative to the config file, or a tsconfig `paths`
   alias. Generated imports use the most specific alias, else a relative path.
 - Default selection is every exported, non-abstract class. A module's
-  `select: { export, decorators, nameGlob }` narrows it; a class must meet every
-  criterion set. Decorators match by name, so composed ones must be listed.
+  `select: { export, decorators, nameGlob, excludeClasses, excludeNameGlob }`
+  narrows it; positive criteria must all hold and then `excludeClasses` (exact
+  names) and `excludeNameGlob` (glob) drop classes. Decorators match by name, so
+  composed ones must be listed. The build warns when two selected classes pass the
+  same plain-identifier first decorator argument (a same-token heuristic).
 - Never edit a `*.bundle.ts` by hand — change the classes or the config and
   rerun `tic build`.
 - Files take part when they match no `exclude` glob **and** an

package/README.md

@@ -95,14 +95,46 @@ By default every exported, non-abstract class of a scanned file is registered.
 }
 ```
 
-| Criterion    | Default | Meaning                                                                                                     |
-| ------------ | ------- | ----------------------------------------------------------------------------------------------------------- |
-| `export`     | `any`   | `any`, `named` or `default` — which exports count                                                           |
-| `decorators` | —       | The class must carry one of these, by name — also renamed imports and `@ioc.register()`; list composed ones |
-| `nameGlob`   | —       | Glob on the class name; an anonymous default export is named after its file (`user-service.ts` → `UserService`) |
+| Criterion          | Default | Meaning                                                                                                     |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------- |
+| `export`           | `any`   | `any`, `named` or `default` — which exports count                                                           |
+| `decorators`       | —       | The class must carry one of these, by name — also renamed imports and `@ioc.register()`; list composed ones |
+| `nameGlob`         | —       | Glob on the class name; an anonymous default export is named after its file (`user-service.ts` → `UserService`) |
+| `excludeClasses`   | —       | Class names to drop, e.g. `["MockDashboardRepository"]`                                                     |
+| `excludeNameGlob`  | —       | Glob the class name must **not** match, e.g. `"*Mock"`                                                      |
 
 Abstract and non-exported classes are never registered.
 
+### Excluding a single class
+
+When a real implementation and a test-only stand-in are both decorated and both
+bind the same token, registration is last-wins and the stand-in silently wins. A
+`tic.exports.*` predicate works, but forces a hand-maintained name list in code;
+`excludeClasses` and `excludeNameGlob` drop a class right in the config:
+
+```json
+"select": {
+  "decorators": ["repository", "service"],
+  "excludeClasses": ["MockDashboardRepository"],
+  "excludeNameGlob": "*Fake"
+}
+```
+
+Both apply after every other criterion, so they can be combined with
+`decorators` and `nameGlob` freely. Reach for `filterExports` when the rule
+needs more than the class name.
+
+As a safety net, the build warns when two selected classes pass the same
+plain-identifier first argument to a decorator — usually the binding token, as in
+`@repository(IDashboardRepositoryToken)`. The check is syntactic (aliased imports
+are not resolved), so it can only be a heuristic:
+
+```text
+tic: warning: bundles[0]: decorator token "IDashboardRepositoryToken" is passed by
+HttpDashboardRepository, MockDashboardRepository; registration is last-wins,
+exclude one with select.excludeClasses
+```
+
 ## Including files with a predicate
 
 When globs aren't enough, decide in code which files take part:

package/cjm/build.js

@@ -28,7 +28,10 @@ function build({ config = config_1.DEFAULT_CONFIG_FILE, cwd = process.cwd(), che
         fileOf: (bundle) => bundle.filterExports,
         load: exportPredicate_1.loadExportPredicate,
     });
-    const generated = resolved.bundles.map((bundle) => generate(resolved, bundle, paths, { include: includeFor(bundle), filterExports: filterExportsFor(bundle) }));
+    const generated = resolved.bundles.map((bundle, i) => generate(resolved, bundle, `bundles[${i}]`, paths, {
+        include: includeFor(bundle),
+        filterExports: filterExportsFor(bundle),
+    }));
     const outputs = generated.map(({ bundle, content, registrations }) => {
         const current = (0, node_fs_1.existsSync)(bundle.output) ? (0, node_fs_1.readFileSync)(bundle.output, 'utf8') : undefined;
         const status = current === content ? 'unchanged' : check ? 'stale' : 'written';
@@ -38,7 +41,11 @@ function build({ config = config_1.DEFAULT_CONFIG_FILE, cwd = process.cwd(), che
         }
         return { file: bundle.output, bundle: bundle.name, status, registrations, content };
     });
-    return { config: resolved.file, outputs, warnings: resolved.warnings };
+    return {
+        config: resolved.file,
+        outputs,
+        warnings: [...resolved.warnings, ...generated.flatMap((g) => g.warnings)],
+    };
 }
 function predicateResolver({ override, conventional, fileOf, load, }) {
     const loaded = new Map();
@@ -53,7 +60,7 @@ function predicateResolver({ override, conventional, fileOf, load, }) {
         return loaded.get(file);
     };
 }
-function generate(config, bundle, paths, { include, filterExports }) {
+function generate(config, bundle, field, paths, { include, filterExports }) {
     const relative = (file) => (0, glob_1.toPosix)(node_path_1.default.relative(config.dir, file));
     const outputs = new Set(config.bundles.map((m) => m.output));
     const excludes = bundle.exclude.map(glob_1.globToRegExp);
@@ -86,5 +93,21 @@ function generate(config, bundle, paths, { include, filterExports }) {
         namespaces: bundle.namespaces.map((ns) => ns.path),
         classes,
     });
-    return { bundle, content, registrations: classes.length };
+    return { bundle, content, registrations: classes.length, warnings: tokenCollisions(classes, field) };
+}
+function tokenCollisions(classes, field) {
+    const owners = new Map();
+    for (const { className, tokens } of classes) {
+        for (const token of tokens) {
+            const names = owners.get(token) ?? [];
+            if (!names.includes(className))
+                names.push(className);
+            owners.set(token, names);
+        }
+    }
+    return [...owners]
+        .filter(([, names]) => names.length > 1)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([token, names]) => `${field}: decorator token "${token}" is passed by ${names.join(', ')}; ` +
+        `registration is last-wins, exclude one with select.excludeClasses`);
 }

package/cjm/config.js

@@ -38,7 +38,7 @@ function toNamespace(value, field) {
         return fail(`${field}.recursive`, 'a boolean');
     return { path: value.path, recursive: value.recursive ?? true };
 }
-const SELECTOR_FIELDS = new Set(['export', 'decorators', 'nameGlob']);
+const SELECTOR_FIELDS = new Set(['export', 'decorators', 'nameGlob', 'excludeClasses', 'excludeNameGlob']);
 function toSelector(value, field) {
     if (value === undefined)
         return { export: 'any' };
@@ -47,7 +47,7 @@ function toSelector(value, field) {
     const unknown = Object.keys(value).find((key) => !SELECTOR_FIELDS.has(key));
     if (unknown)
         throw new errors_1.TicConfigError(`${field}.${unknown}: unknown field`);
-    const { export: kind, decorators, nameGlob } = value;
+    const { export: kind, decorators, nameGlob, excludeClasses, excludeNameGlob } = value;
     if (kind !== undefined && kind !== 'any' && kind !== 'named' && kind !== 'default') {
         return fail(`${field}.export`, '"any", "named" or "default"');
     }
@@ -56,7 +56,19 @@ function toSelector(value, field) {
     }
     if (nameGlob !== undefined && !isNonEmptyString(nameGlob))
         return fail(`${field}.nameGlob`, 'a non-empty string');
-    return { export: kind ?? 'any', decorators, nameGlob: nameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(nameGlob) };
+    if (excludeClasses !== undefined && !(isStringArray(excludeClasses) && excludeClasses.length > 0)) {
+        return fail(`${field}.excludeClasses`, 'a non-empty array of strings');
+    }
+    if (excludeNameGlob !== undefined && !isNonEmptyString(excludeNameGlob)) {
+        return fail(`${field}.excludeNameGlob`, 'a non-empty string');
+    }
+    return {
+        export: kind ?? 'any',
+        decorators,
+        nameGlob: nameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(nameGlob),
+        excludeClasses,
+        excludeNameGlob: excludeNameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(excludeNameGlob),
+    };
 }
 function toBundle(value, field, dir) {
     if (!isObject(value))

package/cjm/scan.js

@@ -114,6 +114,10 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         }
     }
     const decoratorsOf = (node) => (ts.getDecorators(node) ?? []).map((d) => decoratorName(d, imports)).filter((n) => !!n);
+    const tokensOf = (node) => (ts.getDecorators(node) ?? [])
+        .map((d) => (ts.isCallExpression(d.expression) ? d.expression.arguments[0] : undefined))
+        .filter((arg) => !!arg && ts.isIdentifier(arg))
+        .map((arg) => arg.text);
     return exported
         .map(({ node, local, exportName }) => ({ node: node ?? (local ? classes.get(local) : undefined), exportName }))
         .filter((e) => !!e.node)
@@ -122,6 +126,7 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         exportName,
         className: node.name?.text ?? nameFromFile(file),
         decorators: decoratorsOf(node),
+        tokens: tokensOf(node),
     }))
         .filter(({ node, exportName, className, decorators }) => {
         if (hasModifier(node, ts.SyntaxKind.AbstractKeyword))
@@ -130,15 +135,22 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
             return false;
         if (selector.decorators && !selector.decorators.some((name) => decorators.includes(name)))
             return false;
-        return !selector.nameGlob || selector.nameGlob.test(className);
+        if (selector.nameGlob && !selector.nameGlob.test(className))
+            return false;
+        if (selector.excludeClasses?.includes(className))
+            return false;
+        if (selector.excludeNameGlob?.test(className))
+            return false;
+        return true;
     })
         .sort((a, b) => a.node.pos - b.node.pos)
-        .map(({ exportName, className, decorators }) => ({
+        .map(({ exportName, className, decorators, tokens }) => ({
         file,
         exportName,
         localName: exportName === 'default' ? className : exportName,
         className,
         isDefault: exportName === 'default',
         decorators,
+        tokens,
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-ioc-container/bundler",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Bundles your dependencies into a single container module for ts-ioc-container: the `tic` CLI scans folders (by path or tsconfig alias) and generates one typed bundle that registers every class — `container.useModule(new AppBundle())`.",
   "publishConfig": {
     "access": "public",

package/tic.schema.json

@@ -99,6 +99,20 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "Glob the class name must match, e.g. \"*Service\". An anonymous default export is named after its file."
+              },
+              "excludeClasses": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Class names to drop after selection, e.g. one test double sitting next to the real registration in the same file."
+              },
+              "excludeNameGlob": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Glob the class name must NOT match, e.g. \"*Mock\". An anonymous default export is named after its file."
               }
             }
           },

package/typings/build.d.ts

@@ -27,7 +27,11 @@ export interface BuildResult {
     /** Absolute path of the config that was built. */
     config: string;
     outputs: OutputResult[];
-    /** Non-fatal problems found while resolving the config, e.g. an `exclude` that drops a default test glob. */
+    /**
+     * Non-fatal problems found while building, e.g. an `exclude` that drops a default
+     * test glob or two selected classes passing the same decorator token. Each warning
+     * names the bundle field it belongs to.
+     */
     warnings: string[];
 }
 /**

package/typings/config.d.ts

@@ -12,12 +12,21 @@ export interface ClassSelector {
     decorators?: string[];
     /** A glob the class name must match, e.g. `*Service`. An anonymous default export is named after its file. */
     nameGlob?: string;
+    /**
+     * Class names to drop after selection, e.g. one test double sitting next to the
+     * real registration in the same file. Unlike `filterExports` this needs no file.
+     */
+    excludeClasses?: string[];
+    /** A glob the class name must NOT match, e.g. `*Mock`. An anonymous default export is named after its file. */
+    excludeNameGlob?: string;
 }
-/** A {@link ClassSelector} with its defaults filled in and its `nameGlob` compiled. */
+/** A {@link ClassSelector} with its defaults filled in and its globs compiled. */
 export interface ResolvedSelector {
     export: ExportKind;
     decorators?: string[];
     nameGlob?: RegExp;
+    excludeClasses?: string[];
+    excludeNameGlob?: RegExp;
 }
 export interface NamespaceConfig {
     /** A folder relative to the config file (`./src/services`) or a tsconfig `paths` alias (`@app/services`). */

package/typings/scan.d.ts

@@ -11,6 +11,12 @@ export interface DiscoveredClass {
     isDefault: boolean;
     /** Names of the class's decorators, renamed imports resolved. */
     decorators: string[];
+    /**
+     * Plain-identifier first arguments of the class's decorators, e.g. the token in
+     * `@repository(Token)`; an empty array when a decorator takes none. Syntax only:
+     * used to warn when two classes pass the same identifier.
+     */
+    tokens: string[];
 }
 /** Source files of `dir`, sorted by path so the generated output is stable across machines. */
 export declare function listSourceFiles(dir: string, recursive: boolean, isExcluded: (file: string) => boolean): string[];