@ts-ioc-container/bundler 0.0.0

package/lib/exportPredicate.ts

@@ -0,0 +1,45 @@
+import { conventionalNames, findConventionalFile, loadPredicateFile } from './predicateFile';
+import type { FilterPredicate } from './utils';
+
+/** What an {@link ExportPredicate} decides on: one exported class of a parsed file. */
+export interface ExportContext {
+  /** The file's path relative to the config file, `/`-separated: `src/services/Logger.ts`. */
+  filename: string;
+  /** The name the class is exported under; `'default'` for a default export. */
+  exportName: string;
+  /** The declared class name; an anonymous default export is named after its file. */
+  className: string;
+  isDefault: boolean;
+  /** Names of the class's decorators, renamed imports resolved (`register as reg` -> `'register'`). */
+  decorators: string[];
+  /** The file-name tags `byTags` reads: `Report.production.eu.ts` -> `['production', 'eu']`. */
+  tags: string[];
+}
+
+/**
+ * Decides, right after a file is parsed, whether one of its exported classes becomes a
+ * registration. It runs on every exported, non-abstract class that passes `select`.
+ *
+ * @example
+ * // tic.exports.ts, next to tic.config.json - picked up by convention
+ * const filterExports: ExportPredicate = ({ exportName }) => !/(Stub|Mock|Fake)$/.test(exportName);
+ * export default filterExports;
+ */
+export type ExportPredicate = FilterPredicate<ExportContext>;
+
+/** Export predicate files looked up next to the config, in this order, when no bundle names one. */
+export const EXPORTS_CONVENTION = conventionalNames('tic.exports');
+
+/** The conventional export predicate file in `dir`, if there is one. */
+export function findConventionalExportPredicate(dir: string): string | undefined {
+  return findConventionalFile(dir, 'tic.exports');
+}
+
+/**
+ * Loads an {@link ExportPredicate} file (see `loadPredicateFile` for formats and caching).
+ *
+ * @throws {TicConfigError} when the file is missing or does not export a function.
+ */
+export function loadExportPredicate(file: string): ExportPredicate {
+  return loadPredicateFile<ExportPredicate>(file, 'ExportPredicate');
+}

package/lib/glob.ts

@@ -0,0 +1,24 @@
+/**
+ * Converts a glob to an anchored RegExp over `/`-separated paths: `**` spans
+ * folders (`**\/` also matches none), `*` and `?` stay within one segment.
+ */
+export function globToRegExp(glob: string): RegExp {
+  let source = '';
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === '*' && glob[i + 1] === '*') {
+      const slash = glob[i + 2] === '/';
+      source += slash ? '(?:.*/)?' : '.*';
+      i += slash ? 2 : 1;
+    } else if (char === '*') {
+      source += '[^/]*';
+    } else if (char === '?') {
+      source += '[^/]';
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+export const toPosix = (file: string): string => file.split('\\').join('/');

package/lib/inclusion.ts

@@ -0,0 +1,61 @@
+import { conventionalNames, findConventionalFile, loadPredicateFile } from './predicateFile';
+import type { FilterPredicate } from './utils';
+
+/** What an {@link InclusionPredicate} decides on. */
+export interface InclusionContext {
+  /** The file's path relative to the config file, `/`-separated: `src/services/Logger.ts`. */
+  filename: string;
+}
+
+/**
+ * Decides whether a scanned file takes part in code generation. A file takes
+ * part only when it matches no `exclude` glob and the predicate returns `true`.
+ *
+ * @example
+ * // tic.include.ts, next to tic.config.json - picked up by convention
+ * const include: InclusionPredicate = ({ filename }) => !filename.includes('/legacy/');
+ * export default include;
+ */
+export type InclusionPredicate = FilterPredicate<InclusionContext>;
+
+/**
+ * An {@link InclusionPredicate} over a file's tags, the dot-separated parts of its name between
+ * the base name and the extension. Wrap it with {@link byTags} to use it anywhere an
+ * `InclusionPredicate` goes.
+ *
+ * @example
+ * // StripeGateway.production.ts joins production only; Shared.ts joins every environment
+ * const ENVS = ['development', 'production', 'test'];
+ * export default byTags((tags) => tags.filter((t) => ENVS.includes(t)).every((t) => t === process.env.TIC_ENV));
+ */
+export type TagInclusionPredicate = (tags: string[], context: InclusionContext) => boolean;
+
+/** `src/Report.production.eu.ts` -> `['production', 'eu']`; `src/Shared.ts` -> `[]`. */
+export function fileTags(filename: string): string[] {
+  return filename
+    .slice(filename.lastIndexOf('/') + 1)
+    .split('.')
+    .slice(1, -1);
+}
+
+/** Wraps a {@link TagInclusionPredicate} into the {@link InclusionPredicate} the bundler calls. */
+export function byTags(predicate: TagInclusionPredicate): InclusionPredicate {
+  return (context) => predicate(fileTags(context.filename), context);
+}
+
+/** Predicate files looked up next to the config, in this order, when no bundle names one. */
+export const INCLUSION_CONVENTION = conventionalNames('tic.include');
+
+/** The conventional inclusion predicate file in `dir`, if there is one. */
+export function findConventionalPredicate(dir: string): string | undefined {
+  return findConventionalFile(dir, 'tic.include');
+}
+
+/**
+ * Loads an {@link InclusionPredicate} file (see `loadPredicateFile` for formats and caching).
+ *
+ * @throws {TicConfigError} when the file is missing or does not export a function.
+ */
+export function loadInclusionPredicate(file: string): InclusionPredicate {
+  return loadPredicateFile<InclusionPredicate>(file, 'InclusionPredicate');
+}

package/lib/index.ts

@@ -0,0 +1,40 @@
+export { build, type BuildOptions, type BuildResult, type OutputResult, type OutputStatus } from './build';
+export { run, type CliIo } from './cli';
+export {
+  loadConfig,
+  resolveConfig,
+  DEFAULT_CONFIG_FILE,
+  DEFAULT_EXCLUDE,
+  DEFAULT_BUNDLE_NAME,
+  type TicConfig,
+  type BundleConfig,
+  type NamespaceConfig,
+  type ClassSelector,
+  type ExportKind,
+  type ResolvedSelector,
+  type ResolvedConfig,
+  type ResolvedBundle,
+} from './config';
+export { ImportPaths } from './ImportPaths';
+export { type FilterPredicate } from './utils';
+export {
+  type ExportPredicate,
+  type ExportContext,
+  EXPORTS_CONVENTION,
+  findConventionalExportPredicate,
+  loadExportPredicate,
+} from './exportPredicate';
+export {
+  type InclusionPredicate,
+  type InclusionContext,
+  type TagInclusionPredicate,
+  byTags,
+  fileTags,
+  INCLUSION_CONVENTION,
+  findConventionalPredicate,
+  loadInclusionPredicate,
+} from './inclusion';
+export { findClasses, listSourceFiles, type DiscoveredClass } from './scan';
+export { emitBundle, type EmitInput } from './emit';
+export { globToRegExp } from './glob';
+export { TicError, TicConfigError, NamespaceNotFoundError } from './errors';

package/lib/predicateFile.ts

@@ -0,0 +1,36 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { TicConfigError } from './errors';
+import type { FilterPredicate } from './utils';
+
+const EXTENSIONS = ['cjs', 'js', 'mjs', 'ts', 'cts', 'mts'];
+
+/** `tic.include` -> `tic.include.cjs`, `tic.include.js`, ... in lookup order. */
+export const conventionalNames = (base: string): string[] => EXTENSIONS.map((ext) => `${base}.${ext}`);
+
+/** The first conventional file for `base` that exists in `dir`, if any. */
+export function findConventionalFile(dir: string, base: string): string | undefined {
+  return conventionalNames(base)
+    .map((name) => path.join(dir, name))
+    .find((file) => existsSync(file));
+}
+
+/**
+ * Loads a predicate file synchronously with `require` - `.cjs` / `.js`, ES modules
+ * (Node 22.12+) and `.ts` (Node with type stripping). Its default export, or
+ * `module.exports` itself, is the predicate. Like any `require`d module it is loaded
+ * once per process, so a predicate that depends on the environment should read it
+ * when called, not when loaded.
+ *
+ * @throws {TicConfigError} when the file is missing or does not export a function.
+ */
+export function loadPredicateFile<T extends FilterPredicate<never>>(file: string, typeName: string): T {
+  if (!existsSync(file)) throw new TicConfigError(`predicate file not found: ${file}`);
+  const loaded: unknown = createRequire(file)(file);
+  const predicate = typeof loaded === 'function' ? loaded : (loaded as { default?: unknown } | undefined)?.default;
+  if (typeof predicate !== 'function') {
+    throw new TicConfigError(`${file} must export an ${typeName} function (default export or module.exports)`);
+  }
+  return predicate as T;
+}

package/lib/render.ts

@@ -0,0 +1,19 @@
+import '../tpl/index.cjs';
+import Handlebars from 'handlebars';
+
+// A protocol is the declarative definition (schema) of a generated file, written as a Handlebars
+// template in lib/protocols/. `hbs:compile` precompiles them into tpl/index.cjs, which registers each
+// one in the process-global `Handlebars.templates` under its file basename. Output is TypeScript,
+// not HTML, so protocols interpolate with `{{{ }}}` and helpers return plain strings.
+Handlebars.registerHelper('join', (items: string[], separator: string) => items.join(separator));
+
+/**
+ * Renders a precompiled protocol, looked up by its file basename (`Bundle.ts.hbs`).
+ *
+ * @throws {Error} when no protocol is registered under `name`.
+ */
+export function renderProtocol(name: string, data: unknown): string {
+  const protocol = Handlebars.templates?.[name];
+  if (!protocol) throw new Error(`Protocol not found: ${name}`);
+  return protocol(data);
+}

package/lib/scan.ts

@@ -0,0 +1,133 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import * as ts from 'typescript';
+import type { ResolvedSelector } from './config';
+
+/** An exported class the generated bundle registers. */
+export interface DiscoveredClass {
+  file: string;
+  /** The name it is exported under; `default` for a default export. */
+  exportName: string;
+  /** The local name the generated bundle would like to import it under. */
+  localName: string;
+  /** The declared class name; an anonymous default export is named after its file. */
+  className: string;
+  isDefault: boolean;
+  /** Names of the class's decorators, renamed imports resolved. */
+  decorators: string[];
+}
+
+const SOURCE_FILE = /\.(tsx?|mts|cts)$/;
+const DECLARATION_FILE = /\.d\.[mc]?tsx?$/;
+
+/** Source files of `dir`, sorted by path so the generated output is stable across machines. */
+export function listSourceFiles(dir: string, recursive: boolean, isExcluded: (file: string) => boolean): string[] {
+  const files: string[] = [];
+  const walk = (current: string) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (recursive && entry.name !== 'node_modules') walk(full);
+      } else if (SOURCE_FILE.test(entry.name) && !DECLARATION_FILE.test(entry.name) && !isExcluded(full)) {
+        files.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return files.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+const hasModifier = (node: ts.Node, kind: ts.SyntaxKind) =>
+  ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((m) => m.kind === kind);
+
+/** `@register`, `@register(...)`, `@ioc.register(...)` -> `register`; renamed imports map back to the imported name. */
+function decoratorName(decorator: ts.Decorator, imports: Map<string, string>): string | undefined {
+  const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+  if (ts.isIdentifier(callee)) return imports.get(callee.text) ?? callee.text;
+  if (ts.isPropertyAccessExpression(callee)) return callee.name.text;
+  return undefined;
+}
+
+/**
+ * `user-service.ts` -> `UserService`: the import name of an anonymous default-exported class.
+ * File-name tags are not part of it: `user-service.production.ts` -> `UserService`.
+ */
+function nameFromFile(file: string): string {
+  const words = path
+    .basename(file)
+    .split('.')[0]
+    .split(/[^A-Za-z0-9_$]+/)
+    .filter(Boolean);
+  const name = words.map((w: string) => w[0].toUpperCase() + w.slice(1)).join('');
+  return /^[A-Za-z_$]/.test(name) ? name : `_${name}`;
+}
+
+/**
+ * The exported, non-abstract classes of one file that `selector` selects, in
+ * declaration order. Syntax only: decorators are recognised by name, not by type.
+ */
+export function findClasses(
+  file: string,
+  selector: ResolvedSelector,
+  text = readFileSync(file, 'utf8'),
+): DiscoveredClass[] {
+  const kind = file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false, kind);
+
+  const imports = new Map<string, string>(); // local name -> imported name
+  const classes = new Map<string, ts.ClassDeclaration>();
+  const exported: { node: ts.ClassDeclaration | undefined; local?: string; exportName: string }[] = [];
+
+  for (const statement of source.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const bindings = statement.importClause?.namedBindings;
+      if (bindings && ts.isNamedImports(bindings)) {
+        for (const el of bindings.elements) imports.set(el.name.text, (el.propertyName ?? el.name).text);
+      }
+    } else if (ts.isClassDeclaration(statement)) {
+      if (statement.name) classes.set(statement.name.text, statement);
+      if (hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+        const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword);
+        exported.push({ node: statement, exportName: isDefault ? 'default' : statement.name!.text });
+      }
+    } else if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && !statement.isTypeOnly) {
+      const clause = statement.exportClause;
+      if (clause && ts.isNamedExports(clause)) {
+        for (const el of clause.elements) {
+          if (!el.isTypeOnly)
+            exported.push({ node: undefined, local: (el.propertyName ?? el.name).text, exportName: el.name.text });
+        }
+      }
+    } else if (ts.isExportAssignment(statement) && !statement.isExportEquals && ts.isIdentifier(statement.expression)) {
+      exported.push({ node: undefined, local: statement.expression.text, exportName: 'default' });
+    }
+  }
+
+  const decoratorsOf = (node: ts.ClassDeclaration) =>
+    (ts.getDecorators(node) ?? []).map((d) => decoratorName(d, imports)).filter((n): n is string => !!n);
+
+  return exported
+    .map(({ node, local, exportName }) => ({ node: node ?? (local ? classes.get(local) : undefined), exportName }))
+    .filter((e): e is { node: ts.ClassDeclaration; exportName: string } => !!e.node)
+    .map(({ node, exportName }) => ({
+      node,
+      exportName,
+      className: node.name?.text ?? nameFromFile(file),
+      decorators: decoratorsOf(node),
+    }))
+    .filter(({ node, exportName, className, decorators }) => {
+      if (hasModifier(node, ts.SyntaxKind.AbstractKeyword)) return false;
+      if (selector.export !== 'any' && (exportName === 'default') !== (selector.export === 'default')) return false;
+      if (selector.decorators && !selector.decorators.some((name) => decorators.includes(name))) return false;
+      return !selector.nameGlob || selector.nameGlob.test(className);
+    })
+    .sort((a, b) => a.node.pos - b.node.pos)
+    .map(({ exportName, className, decorators }) => ({
+      file,
+      exportName,
+      localName: exportName === 'default' ? className : exportName,
+      className,
+      isDefault: exportName === 'default',
+      decorators,
+    }));
+}

package/lib/utils.ts

@@ -0,0 +1,2 @@
+/** Decides whether a value is kept. The base of every predicate the bundler takes. */
+export type FilterPredicate<Target> = (value: Target) => boolean;

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@ts-ioc-container/bundler",
+  "version": "0.0.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 \u2014 `container.useModule(new AppBundle())`.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "ibabkin <igba14@gmail.com>",
+  "homepage": "https://github.com/IgorBabkin/ts-ioc-container/tree/main/packages/bundler#readme",
+  "license": "ISC",
+  "sideEffects": false,
+  "main": "cjm/index.js",
+  "types": "typings/index.d.ts",
+  "bin": {
+    "ts-ioc-container": "cjm/bin.js",
+    "tic": "cjm/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./typings/index.d.ts",
+      "default": "./cjm/index.js"
+    },
+    "./tic.schema.json": "./tic.schema.json",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "dependency-injection",
+    "ioc",
+    "di",
+    "codegen",
+    "bundler",
+    "cli",
+    "component-scan",
+    "tsconfig-paths",
+    "ts-ioc-container"
+  ],
+  "files": [
+    "cjm/**/*",
+    "typings/**/*",
+    "tpl/**/*",
+    "lib/**/*",
+    "!lib/**/*.hbs",
+    "tic.schema.json",
+    "AGENTS.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorBabkin/ts-ioc-container",
+    "directory": "packages/bundler"
+  },
+  "scripts": {
+    "hbs:compile": "mkdir -p tpl && handlebars lib/protocols/*.hbs -f tpl/index.cjs -c handlebars",
+    "build:cjm": "node ../scripts/build.mjs cjm",
+    "build:types": "node ../scripts/build.mjs types",
+    "build": "pnpm run hbs:compile && pnpm run build:cjm && pnpm run build:types",
+    "prepack": "pnpm run hbs:compile",
+    "test": "pnpm run hbs:compile && pnpm run build:cjm && vitest run",
+    "test:coverage": "pnpm run hbs:compile && pnpm run build:cjm && vitest run --coverage --coverage.reporter=lcov",
+    "type-check": "pnpm run hbs:compile && tsc --noEmit",
+    "lint": "eslint lib/**/*.ts __tests__/**/*.ts",
+    "lint:fix": "pnpm run lint --fix",
+    "format": "prettier --write \"lib/**/*.ts\" \"__tests__/**/*.ts\"",
+    "format:check": "prettier --check \"lib/**/*.ts\" \"__tests__/**/*.ts\""
+  },
+  "dependencies": {
+    "handlebars": "^4.7.9"
+  },
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "reflect-metadata": "^0.2.2",
+    "ts-ioc-container": "workspace:*",
+    "typescript": "5.8.3",
+    "unplugin-swc": "^1.6.0",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">= 18"
+  }
+}

package/tic.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/IgorBabkin/ts-ioc-container/tree/main/packages/bundler/tic.schema.json",
+  "title": "tic.config.json",
+  "description": "Bundles generated by `tic build` (@ts-ioc-container/bundler). Relative paths resolve against this file's directory.",
+  "type": "object",
+  "required": [
+    "bundles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "tsconfig": {
+      "type": "string",
+      "description": "tsconfig whose `paths` aliases namespaces and imports may use. Default `tsconfig.json`, which may be absent."
+    },
+    "importExtension": {
+      "type": "string",
+      "description": "Extension of generated imports, e.g. \".js\". Inferred from the tsconfig: \".js\" under node16/nodenext resolution, none otherwise."
+    },
+    "bundles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "output",
+          "namespaces"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "output": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The bundle file (convention: *.bundle.ts)."
+          },
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Za-z_$][\\w$]*$",
+            "default": "Bundle",
+            "description": "Name of the generated class, an IContainerModule."
+          },
+          "namespaces": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Folders to scan: paths relative to this file (./src/services) or tsconfig paths aliases (@app/services).",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "path"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "recursive": {
+                      "type": "boolean",
+                      "default": true
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "select": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "How target classes are picked out of a file. A class is selected when it is exported, not abstract, and meets every criterion set here; omit it to register every exported class.",
+            "properties": {
+              "export": {
+                "enum": [
+                  "any",
+                  "named",
+                  "default"
+                ],
+                "default": "any",
+                "description": "Which exports count."
+              },
+              "decorators": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "The class must carry one of these decorators, recognised by name (e.g. \"register\", or a composed decorator)."
+              },
+              "nameGlob": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Glob the class name must match, e.g. \"*Service\". An anonymous default export is named after its file."
+              }
+            }
+          },
+          "exclude": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "default": [
+              "**/*.spec.ts",
+              "**/*.test.ts",
+              "**/*.spec.tsx",
+              "**/*.test.tsx",
+              "**/__tests__/**",
+              "**/node_modules/**"
+            ],
+            "description": "Globs, relative to this file, of files never scanned. Replaces the default when given."
+          },
+          "include": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A file exporting an InclusionPredicate ((context: { filename }) => boolean), relative to this file. Overrides the conventional tic.include.* next to this file. A file takes part only when it matches no `exclude` glob and the predicate returns true."
+          },
+          "filterExports": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A file exporting an ExportPredicate ((context: { filename, exportName, className, isDefault, decorators, tags }) => boolean), relative to this file. Runs on every exported, non-abstract class that passes `select`, right after parsing. Overrides the conventional tic.exports.* next to this file."
+          }
+        }
+      }
+    }
+  }
+}