@digital-alchemy/eslint

A framework-correctness ESLint plugin for Digital-Alchemy TypeScript applications. It enforces patterns and constraints specific to the DA runtime — service wiring, module boundaries, lifecycle ordering — that generic TypeScript linters cannot model.

Note: Rules that inspect type information require typed linting to be configured. Add parserOptions.projectService: true (or parserOptions.project) to your languageOptions block; without it, type-aware rules will be disabled or throw at load time.

Installation

yarn add --dev @digital-alchemy/eslint

Requires ESLint 9 or 10 and Node 20+.

Usage

Add the plugin to your flat config and extend the recommended config:

// eslint.config.mjs
import daEslint from "@digital-alchemy/eslint";

export default [
  // Spread recommended to get all default rule settings
  daEslint.configs.recommended,

  // Your own overrides below
  {
    languageOptions: {
      parserOptions: {
        // Required for type-aware rules
        projectService: true,
      },
    },
  },
];

Registering the plugin manually

If you prefer to enable only specific rules rather than the full recommended preset:

import daEslint from "@digital-alchemy/eslint";

export default [
  {
    plugins: { "digital-alchemy": daEslint },
    rules: {
      // "digital-alchemy/<rule-name>": "error",
    },
  },
];

Rules

🔧 Automatically fixable by the --fix CLI option.
💭 Requires type information.

Name	Description	🔧	💭
module-declaration-merge	Require a LoadedModules declaration merge in the same file as CreateApplication/CreateLibrary, after the definition
module-local-imports	Module files must source their services from local subfolders, not parent directories
no-construction-side-effects	Disallow side-effectful statements at the root of a service factory. Construction is for wiring definitions; side effects belong in lifecycle hooks.
no-empty-config-default	Disallow empty-string defaults in Digital Alchemy configuration entries
no-service-class	Disallow class definitions in service files.
no-service-external-mutation	Disallow mutating array methods called on bindings defined outside a service factory
no-service-module-scope-state	.service.mts files must not declare module-scope mutable or derived state; static constants (primitive literals, static arrays/objects, new Map/Set([...literals]), static binary expressions, and hoistable computed expressions like [...].join(SEP)) are allowed at module scope per no-service-primitive-const. All runtime state must live in the service factory closure. Complements (does not duplicate) no-service-primitive-const (which targets static consts INSIDE the factory) and service-preamble-limit.
no-sibling-service-import	.service.mts files must not import from sibling service files. Move shared constants/types to a contracts module and share logic through the framework (dependency injection).
no-toplevel-config	Disallow top-level config access in DA service functions
no-undeclared-module-dependency	Disallow a service referencing a module (via TServiceParams or config.) that its owner does not declare in depends/libraries.		💭
no-unnecessary-priority-init	Disallow a priorityInit entry that no sibling reads during construction (it orders nothing).		💭
no-unused-service-params	Disallow destructuring a TServiceParams member that is never used in a service.	🔧
priority-init-order	Disallow a priorityInit order where a producer wires after a consumer that reads it during construction.		💭
require-priority-init	Require a service to be listed in priorityInit when a sibling reads its API during construction.		💭

Typed linting

Many rules in this plugin inspect TypeScript type information. To enable them you must configure typed linting in your project:

// eslint.config.mjs
export default [
  {
    languageOptions: {
      parserOptions: {
        projectService: true,           // recommended (ESLint 9+)
        // OR: project: ["tsconfig.json"],  // explicit path form
      },
    },
  },
];

Without typed linting, type-aware rules will either be silently skipped or will produce a configuration error at startup.

Links

• Digital-Alchemy core
• Documentation
• Bugs / feature requests
• Sponsor

License

MIT