@ts-ioc-container/bundler 1.2.0 → 1.3.0

package/AGENTS.md

@@ -13,11 +13,14 @@ 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, excludeClasses, excludeNameGlob }`
+  `select: { export, decorators, nameGlob, excludeClasses, excludeNameGlob, excludeAliases }`
   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).
+  names), `excludeNameGlob` (glob) and `excludeAliases` (tsconfig `paths` aliases
+  the file resolves through, e.g. `services` for `@services/*`) 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), unless a decorator they share has differing arguments
+  (scope-gated, e.g. `@perPage('a')` vs `@perPage('b')`).
 - 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

@@ -102,6 +102,7 @@ By default every exported, non-abstract class of a scanned file is registered.
 | `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"`                                                      |
+| `excludeAliases`   | —       | tsconfig `paths` aliases to drop, e.g. `["services"]` for a `services/*` or `@services/*` alias             |
 
 Abstract and non-exported classes are never registered.
 
@@ -124,6 +125,18 @@ 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.
 
+`excludeAliases` drops classes by the tsconfig `paths` alias their file resolves
+through — handy for excluding a whole namespace without naming its classes:
+
+```json
+"select": {
+  "excludeAliases": ["services"]
+}
+```
+
+An entry matches a `paths` pattern such as `services/*` or `@services/*`; a
+leading `@` and a trailing `/*` may be omitted.
+
 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
@@ -135,6 +148,11 @@ HttpDashboardRepository, MockDashboardRepository; registration is last-wins,
 exclude one with select.excludeClasses
 ```
 
+Classes that are scope-gated are not last-wins, so they do not warn: when the
+colliding classes share a decorator called with different arguments, e.g.
+`@perPage('stations')` vs `@perPage('sessions')`, each scope registers its own
+class and nothing is lost.
+
 ## Including files with a predicate
 
 When globs aren't enough, decide in code which files take part:

package/cjm/ImportPaths.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ImportPaths = void 0;
+exports.normalizeAliasName = normalizeAliasName;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const ts = __importStar(require("typescript"));
@@ -92,6 +93,19 @@ class ImportPaths {
     specifier(fromFile, toFile) {
         const target = (0, glob_1.toPosix)(toFile);
         const bare = target.replace(SOURCE_EXTENSION, '');
+        const best = this.bestAlias(target, bare);
+        if (best)
+            return best.spec;
+        const relative = (0, glob_1.toPosix)(node_path_1.default.relative(node_path_1.default.dirname(fromFile), bare));
+        return `${relative.startsWith('.') ? relative : `./${relative}`}${this.extension}`;
+    }
+    aliasName(file) {
+        const target = (0, glob_1.toPosix)(file);
+        const bare = target.replace(SOURCE_EXTENSION, '');
+        const best = this.bestAlias(target, bare);
+        return best && normalizeAliasName(best.pattern);
+    }
+    bestAlias(target, bare) {
         let best;
         for (const { pattern, targets } of this.aliases) {
             for (const aliasTarget of targets) {
@@ -100,10 +114,7 @@ class ImportPaths {
                     best = match;
             }
         }
-        if (best)
-            return best.spec;
-        const relative = (0, glob_1.toPosix)(node_path_1.default.relative(node_path_1.default.dirname(fromFile), bare));
-        return `${relative.startsWith('.') ? relative : `./${relative}`}${this.extension}`;
+        return best;
     }
     aliasTargets(spec) {
         return this.aliases.flatMap(({ pattern, targets }) => {
@@ -121,14 +132,17 @@ class ImportPaths {
         const wildcard = splitWildcard(aliasTarget);
         if (!wildcard) {
             const exact = aliasTarget === file || aliasTarget.replace(SOURCE_EXTENSION, '') === bare;
-            return exact && !splitWildcard(pattern) ? { spec: pattern, score: Infinity } : undefined;
+            return exact && !splitWildcard(pattern) ? { spec: pattern, score: Infinity, pattern } : undefined;
         }
         const [prefix, suffix] = wildcard;
         if (!bare.startsWith(prefix) || !bare.endsWith(suffix) || bare.length < prefix.length + suffix.length) {
             return undefined;
         }
         const captured = bare.slice(prefix.length, bare.length - suffix.length);
-        return { spec: `${pattern.replace('*', captured)}${this.extension}`, score: prefix.length };
+        return { spec: `${pattern.replace('*', captured)}${this.extension}`, score: prefix.length, pattern };
     }
 }
 exports.ImportPaths = ImportPaths;
+function normalizeAliasName(pattern) {
+    return pattern.replace(/^@/, '').replace(/\/?\*$/, '');
+}

package/cjm/build.js

@@ -76,10 +76,19 @@ function generate(config, bundle, field, paths, { include, filterExports }) {
         for (const file of (0, scan_1.listSourceFiles)(dir, namespace.recursive, isExcluded))
             files.add(file);
     }
+    const excludedAliases = new Set((bundle.select.excludeAliases ?? []).map(ImportPaths_1.normalizeAliasName));
+    const isAliasExcluded = (file) => {
+        if (excludedAliases.size === 0)
+            return false;
+        const alias = paths.aliasName(file);
+        return alias !== undefined && excludedAliases.has(alias);
+    };
     const classes = [...files]
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
         .flatMap((file) => (0, scan_1.findClasses)(file, bundle.select))
         .filter((cls) => {
+        if (isAliasExcluded(cls.file))
+            return false;
         if (!filterExports)
             return true;
         const filename = relative(cls.file);
@@ -97,17 +106,27 @@ function generate(config, bundle, field, paths, { include, filterExports }) {
 }
 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);
+    for (const cls of classes) {
+        for (const token of cls.tokens) {
+            const group = owners.get(token) ?? [];
+            if (!group.some((owner) => owner.className === cls.className))
+                group.push(cls);
+            owners.set(token, group);
         }
     }
     return [...owners]
-        .filter(([, names]) => names.length > 1)
+        .filter(([, group]) => group.length > 1 && !scopeDisjoint(group))
         .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`);
+        .map(([token, group]) => {
+        const names = group.map((cls) => cls.className);
+        return (`${field}: decorator token "${token}" is passed by ${names.join(', ')}; ` +
+            `registration is last-wins, exclude one with select.excludeClasses`);
+    });
+}
+function scopeDisjoint(group) {
+    const [first, ...rest] = group;
+    return first.decoratorCalls.some(({ name, args }) => rest.every((cls) => {
+        const same = cls.decoratorCalls.find((call) => call.name === name);
+        return same !== undefined && same.args.join('\u0000') !== args.join('\u0000');
+    }));
 }

package/cjm/config.js

@@ -38,7 +38,14 @@ 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', 'excludeClasses', 'excludeNameGlob']);
+const SELECTOR_FIELDS = new Set([
+    'export',
+    'decorators',
+    'nameGlob',
+    'excludeClasses',
+    'excludeNameGlob',
+    'excludeAliases',
+]);
 function toSelector(value, field) {
     if (value === undefined)
         return { export: 'any' };
@@ -47,7 +54,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, excludeClasses, excludeNameGlob } = value;
+    const { export: kind, decorators, nameGlob, excludeClasses, excludeNameGlob, excludeAliases } = value;
     if (kind !== undefined && kind !== 'any' && kind !== 'named' && kind !== 'default') {
         return fail(`${field}.export`, '"any", "named" or "default"');
     }
@@ -62,12 +69,16 @@ function toSelector(value, field) {
     if (excludeNameGlob !== undefined && !isNonEmptyString(excludeNameGlob)) {
         return fail(`${field}.excludeNameGlob`, 'a non-empty string');
     }
+    if (excludeAliases !== undefined && !(isStringArray(excludeAliases) && excludeAliases.length > 0)) {
+        return fail(`${field}.excludeAliases`, 'a non-empty array of strings');
+    }
     return {
         export: kind ?? 'any',
         decorators,
         nameGlob: nameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(nameGlob),
         excludeClasses,
         excludeNameGlob: excludeNameGlob === undefined ? undefined : (0, glob_1.globToRegExp)(excludeNameGlob),
+        excludeAliases,
     };
 }
 function toBundle(value, field, dir) {

package/cjm/scan.js

@@ -114,6 +114,13 @@ 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 decoratorCallsOf = (node) => (ts.getDecorators(node) ?? []).flatMap((d) => {
+        const name = decoratorName(d, imports);
+        if (!name)
+            return [];
+        const args = ts.isCallExpression(d.expression) ? d.expression.arguments.map((arg) => arg.getText(source)) : [];
+        return [{ name, args }];
+    });
     const tokensOf = (node) => (ts.getDecorators(node) ?? [])
         .map((d) => (ts.isCallExpression(d.expression) ? d.expression.arguments[0] : undefined))
         .filter((arg) => !!arg && ts.isIdentifier(arg))
@@ -126,6 +133,7 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         exportName,
         className: node.name?.text ?? nameFromFile(file),
         decorators: decoratorsOf(node),
+        decoratorCalls: decoratorCallsOf(node),
         tokens: tokensOf(node),
     }))
         .filter(({ node, exportName, className, decorators }) => {
@@ -144,13 +152,14 @@ function findClasses(file, selector, text = (0, node_fs_1.readFileSync)(file, 'u
         return true;
     })
         .sort((a, b) => a.node.pos - b.node.pos)
-        .map(({ exportName, className, decorators, tokens }) => ({
+        .map(({ exportName, className, decorators, decoratorCalls, tokens }) => ({
         file,
         exportName,
         localName: exportName === 'default' ? className : exportName,
         className,
         isDefault: exportName === 'default',
         decorators,
+        decoratorCalls,
         tokens,
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-ioc-container/bundler",
-  "version": "1.2.0",
+  "version": "1.3.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

@@ -113,6 +113,15 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "Glob the class name must NOT match, e.g. \"*Mock\". An anonymous default export is named after its file."
+              },
+              "excludeAliases": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "tsconfig paths aliases to drop after selection, e.g. [\"services\"] for a `services/*` (or `@services/*`) alias. A class whose file resolves through one of these aliases is dropped. Names may omit a leading `@` and a trailing `/*`."
               }
             }
           },

package/typings/ImportPaths.d.ts

@@ -29,9 +29,18 @@ export declare class ImportPaths {
     resolveNamespace(namespace: string, baseDir: string): string;
     /** The specifier `fromFile` imports `toFile` by: its most specific alias, else a relative path. */
     specifier(fromFile: string, toFile: string): string;
+    /**
+     * The tsconfig `paths` alias `file` is covered by, normalized to its name
+     * (`@app/services/*` -> `app/services`), or `undefined` when no alias covers it.
+     * Used to drop classes by alias (`select.excludeAliases`).
+     */
+    aliasName(file: string): string | undefined;
+    private bestAlias;
     private aliasTargets;
     /** A longer matched target prefix is a more specific alias; an exact file alias beats every wildcard. */
     private matchAlias;
 }
+/** The name of a `paths` alias: `@app/services/*` and `@app/services` both become `app/services`. */
+export declare function normalizeAliasName(pattern: string): string;
 export {};
 //# sourceMappingURL=ImportPaths.d.ts.map

package/typings/config.d.ts

@@ -19,6 +19,12 @@ export interface ClassSelector {
     excludeClasses?: string[];
     /** A glob the class name must NOT match, e.g. `*Mock`. An anonymous default export is named after its file. */
     excludeNameGlob?: string;
+    /**
+     * tsconfig `paths` aliases to drop after selection: a class whose file resolves
+     * through one of these aliases is dropped, e.g. `["services"]` for a `services/*`
+     * (or `@services/*`) alias. Names may omit a leading `@` and a trailing `/*`.
+     */
+    excludeAliases?: string[];
 }
 /** A {@link ClassSelector} with its defaults filled in and its globs compiled. */
 export interface ResolvedSelector {
@@ -27,6 +33,7 @@ export interface ResolvedSelector {
     nameGlob?: RegExp;
     excludeClasses?: string[];
     excludeNameGlob?: RegExp;
+    excludeAliases?: string[];
 }
 export interface NamespaceConfig {
     /** A folder relative to the config file (`./src/services`) or a tsconfig `paths` alias (`@app/services`). */

package/typings/scan.d.ts

@@ -17,6 +17,15 @@ export interface DiscoveredClass {
      * used to warn when two classes pass the same identifier.
      */
     tokens: string[];
+    /**
+     * Each class decorator's name and the source text of its arguments, e.g.
+     * `perPage` with `["'stations'"]`. Syntax only: lets the token-collision check
+     * tell scope-gated classes (`@perPage('a')` vs `@perPage('b')`) apart.
+     */
+    decoratorCalls: {
+        name: string;
+        args: 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[];