@teqfw/di 2.7.0 → 2.8.0

package/ai/usage.md

@@ -1,201 +0,0 @@
-# usage.md
-
-Version: 20260710
-
-## Purpose
-
-This document shows canonical usage patterns for the container. Examples are intentionally short and prioritize supported, recommended forms over convenience shorthand.
-
-## Canonical Module Descriptor
-
-The canonical form of `__deps__` is hierarchical and keyed by export name.
-
-```js
-// @ts-check
-
-export const __deps__ = {
-  default: {
-    cast: "App_Helper_Cast$",
-  },
-};
-
-export default class App_Root {
-  /**
-   * @param {{cast: (value: unknown) => string}} deps
-   */
-  constructor({ cast }) {
-    return {
-      configure(params = {}) {
-        return {
-          name: cast(params.name ?? "app"),
-        };
-      },
-    };
-  }
-}
-```
-
-Dependency module:
-
-```js
-// @ts-check
-
-export default function App_Helper_Cast() {
-  return function cast(value) {
-    return String(value);
-  };
-}
-```
-
-Rules:
-
-- the hierarchical export-scoped form is canonical;
-- each export entry maps constructor dependency names to CDC identifiers;
-- if `__deps__` is omitted, the module has no declared dependencies;
-- dependencies are resolved recursively before instantiation.
-
-## Canonical Container Setup
-
-The container is configured in the composition root before the first resolution.
-
-```js
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import Container from "@teqfw/di";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const container = new Container();
-container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
-```
-
-Namespace roots may also use URL-backed module-specifier bases:
-
-```js
-container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
-```
-
-## Resolve Root Dependency
-
-Applications typically resolve one root dependency and let the container build the full object graph.
-
-```js
-const root = await container.get("App_Root$");
-console.log(root.configure({name: 123}).name);
-console.log(Object.isFrozen(root));
-```
-
-## Named Export
-
-Named exports use the `__ExportName` segment in the CDC and the same hierarchical `__deps__` structure.
-
-```js
-export const __deps__ = {
-  default: {
-    cast: "App_Helper_Cast$",
-  },
-  Factory: {
-    cast: "App_Helper_Cast$",
-  },
-};
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {mode: "runtime"};
-  }
-}
-
-export class Factory {
-  constructor({ cast }) {
-    this.configure = function (params = {}) {
-      return {
-        mode: "factory",
-        name: cast(params.name ?? "app"),
-      };
-    };
-  }
-}
-```
-
-Resolution examples:
-
-```js
-const runtime = await container.get("App_Module$");
-const factory = await container.get("App_Module__Factory$");
-```
-
-Without a lifecycle marker, the export is resolved as-is — the class or function itself, not an instance:
-
-```js
-const FactoryClass = await container.get("App_Module__Factory");
-const factory = new FactoryClass({cast: resolvedCast});
-```
-
-## Singleton And Transient
-
-Common lifecycle-based compositions:
-
-```txt
-App_Service$
-App_Task$$
-App_Task$$$
-```
-
-- `$` creates and reuses a singleton instance;
-- `$$` creates a new instance for each request;
-- `$$$` is a transient alias in the current implementation.
-
-## Wrappers
-
-Wrapper exports are selected by CDC suffixes and are applied after postprocess hooks.
-
-```txt
-App_Service$$_wrapLog_wrapTrace
-```
-
-This pattern is useful when runtime behavior should be decorated without changing the service module contract.
-
-## Platform Modules
-
-CDC may refer to platform modules directly.
-
-```txt
-node:fs
-npm:@humanfs/core
-node:worker_threads
-```
-
-These forms resolve the selected platform module export as-is unless a lifecycle marker is explicitly added.
-
-## Non-Canonical Shorthand
-
-A flat `__deps__` object is a supported shorthand for default-export-only modules, but it is not the canonical model.
-
-```js
-export const __deps__ = {
-  cast: "App_Helper_Cast$",
-};
-
-export default class App_Short {
-  constructor({ cast }) {
-    this.cast = cast;
-  }
-}
-```
-
-Prefer the hierarchical form for new integrations and for any module that exposes named exports.
-
-## Empty Descriptor
-
-Modules with no declared dependencies omit `__deps__` entirely.
-
-```js
-export default class App_Empty {
-  constructor() {
-    this.ready = function () {
-      return true;
-    };
-  }
-}
-```