Cordis Meta-Framework

Common errors

• TypeError: Cannot read properties of undefined (reading 'plugin')

  cause Attempting to call `.plugin()` or other context methods on an uninitialized or incorrectly initialized Cordis instance, often when `new Context()` is not called or its result is not assigned.
  fix Always initialize your Cordis application with `const app = new Context();` and ensure `app` is correctly referenced before calling its methods.

• Error: Service 'myService' already exists in current context

  cause Attempting to register a service with the same name multiple times within the same Cordis context. This can happen if a plugin is registered more than once or if two different plugins provide the same service name.
  fix Ensure each service has a unique name within a given context. If you need different implementations of the same service, use child contexts or conditional plugin registration. For services that should be singletons, manage their registration carefully.

• TS2345: Argument of type 'typeof MyService' is not assignable to parameter of type 'Plugin'.

  cause Your service class or plugin function does not fully conform to the `Plugin` type definition. This often occurs if `static inject` is missing, `constructor` arguments are incorrect, or the service lacks expected properties/methods.
  fix Review your service/plugin definition against Cordis's `Plugin` interface and service class examples. Ensure all `static inject` dependencies are correctly declared and the constructor matches the expected `(ctx: Context, ...injectedDeps)` signature.

Warnings

• breaking Cordis v4 introduces significant breaking changes compared to v3, particularly in its internal architecture and API surface related to context management, service registration, and plugin definition. While specific details for `rc.3` are still being finalized, expect existing v3 codebases to require substantial updates.
  Fix: Consult the official Cordis v4 migration guide once available. Be prepared to refactor service definitions, context interactions, and plugin structures. Pay close attention to changes in `Context` and `Service` class methods.
• gotcha Cordis heavily leverages an "everything is a plugin" philosophy and context-based dependency injection. Misunderstanding the lifecycle of plugins or the scope of services within different contexts can lead to unexpected behavior or services not being available where anticipated.
  Fix: Thoroughly review the documentation on context, services, and plugins. Ensure services are correctly `inject`ed and `provide`d. Use `app.createContext()` for isolated environments or specific configurations.
• gotcha As a modern TypeScript framework, Cordis v4 is built with ESM (ECMAScript Modules) as the primary module system. Attempting to use `require()` for imports in a CommonJS environment without proper configuration (e.g., `"type": "module"` in `package.json` or transpilation) can lead to module resolution errors.
  Fix: Ensure your project is configured for ESM. Use `import` statements exclusively. If in Node.js, set `"type": "module"` in `package.json` or rename files to `.mjs`.
• deprecated Being in a release candidate phase, some APIs or behaviors introduced in earlier `4.0.0-rc` versions may be deprecated or altered before the stable `4.0.0` release. Relying heavily on specific `rc` internal APIs could lead to breakage upon upgrading to a stable version.
  Fix: Prefer documented public APIs. Monitor Cordis's GitHub repository and changelogs for updates on API stability and upcoming changes before the final v4 release. Delay major production deployments until a stable version is available if API stability is critical.

Install

• npm install cordis npm
• yarn add cordis yarn
• pnpm add cordis pnpm

Imports

• Context
  wrong:

  const { Context } = require('cordis')

  correct:

  import { Context } from 'cordis'

  Cordis v4 is ESM-first; CommonJS require() may lead to issues or require specific build configurations. `Context` is the core class for managing services and lifecycles.
• Service
  wrong:

  import Service from 'cordis'

  correct:

  import { Service } from 'cordis'

  `Service` is a named export, not a default. It's the base class for creating extendable, context-aware services within Cordis.
• Plugin
  wrong:

  import { Plugin } from 'cordis'

  correct:

  import type { Plugin } from 'cordis'

  `Plugin` is primarily a TypeScript type used for defining plugin structures. For runtime use, you'd typically define a function or class that adheres to the `Plugin` interface rather than importing `Plugin` as a value.

Quickstart

This quickstart demonstrates creating a Cordis application, registering a custom service with dependency injection, and utilizing context for configuration. It shows how to define a service, make it available within the context, and instantiate it, including creating a child context with overridden configurations.

import { Context, Service } from 'cordis';

interface MyConfig {
  greeting: string;
}

class GreeterService extends Service {
  static inject = ['config']; // Declare dependencies

  constructor(ctx: Context, public config: MyConfig) {
    super(ctx, 'greeter'); // Register service as 'greeter'
    this.logger.info(`GreeterService initialized with config: ${this.config.greeting}`);
  }

  greet(name: string): string {
    return `${this.config.greeting}, ${name}!`;
  }
}

// Main application context
async function bootstrap() {
  const app = new Context();

  // Register the configuration for the greeter service
  app.provide('config', { greeting: 'Hello from Cordis' });

  // Register the GreeterService as a plugin
  app.plugin(GreeterService);

  // Access the greeter service from the context
  const greeter = app.greeter as GreeterService; // Type assertion for convenience
  if (greeter) {
    console.log(greeter.greet('World'));
  } else {
    console.error('Greeter service not found!');
  }

  // Demonstrate a child context with different config
  const childCtx = app.createContext();
  childCtx.provide('config', { greeting: 'Greetings, developer' });
  childCtx.plugin(GreeterService);
  const childGreeter = childCtx.greeter as GreeterService;
  if (childGreeter) {
    console.log(childGreeter.greet('Cordis User'));
  }

  await app.start();
  console.log('Cordis application started successfully.');
  await app.stop();
  console.log('Cordis application stopped.');
}

bootstrap().catch(console.error);