@grest-ts/locator 0.0.5

package/src/GGLocatorScope.ts

@@ -0,0 +1,206 @@
+import type {GGLocatorKey} from "./GGLocatorKey";
+import {GG_ASYNC_STORAGE} from "./GGLocatorStorage";
+import {GGLocatorScopeDebug, GGLocatorScopeDebugList} from "./GGLocatorScopeDebug";
+
+type ConstructorOf<T> = new (...args: any[]) => T;
+
+/**
+ * service-locator pattern for async context cases.
+ */
+export class GGLocatorScope {
+
+    public readonly name: string
+    public readonly serviceName?: string
+    private readonly parent: GGLocatorScope | undefined
+    private readonly values: Map<string, any>
+    private readonly registrationStacks: Map<string, string[]>
+    private readonly creationStack: string[]
+
+    constructor(name: string, parent?: GGLocatorScope, serviceName?: string) {
+        this.name = name
+        this.serviceName = serviceName ?? this.serviceName ?? "Unknown";
+        this.parent = parent
+        this.values = new Map(this.parent?.values ?? []);
+        this.registrationStacks = new Map(this.parent?.registrationStacks ?? []);
+        this.creationStack = new Error().stack?.split("\n").splice(2) ?? [];
+    }
+
+    private _get<T>(name: string): T {
+        const value = this.values.get(name);
+        if (value === undefined) {
+            throw new Error(
+                `Service "${name}" not found in async context!\n` +
+                `Scope tree: ${this.getScopeDebug().toString()}`
+            );
+        }
+        return value;
+    }
+
+    public get<T>(token: GGLocatorKey<T>): T {
+        return this._get(token.name)
+    }
+
+    public tryGet<T>(token: GGLocatorKey<T>): T | undefined {
+        return this.values.get(token.name);
+    }
+
+    public getByTokenName<T>(name: string, type: ConstructorOf<T>): T {
+        const value = this._get(name)
+        if (!(value instanceof type)) {
+            throw new Error("Service is not extending expected type! Expected '" + type?.name + "', but got '" + value?.constructor?.name + "' instead.")
+        }
+        return value as T;
+    }
+
+    public set<T>(token: GGLocatorKey<T>, value: T): void {
+        if (this.values.has(token.name)) {
+            throw new Error(`Scope already has service "${token.name}"!`)
+        }
+        this.overwrite(token, value)
+    }
+
+    public overwrite<T>(token: GGLocatorKey<T>, value: T): void {
+        this.values.set(token.name, value);
+        this.registrationStacks.set(token.name, new Error().stack.split("\n").splice(2));
+    }
+
+    public has<T>(token: GGLocatorKey<T>): boolean {
+        return this.values.has(token.name);
+    }
+
+    /**
+     * Returns all registered key names in this scope.
+     * Used by testkit to report available services to test runner.
+     */
+    public getKeys(): string[] {
+        return Array.from(this.values.keys());
+    }
+
+    // -----------
+
+    private _lifecycleHandler?: (service: GGLocatorLifecycleCallbacks) => void;
+
+    public setLifecycleOwner(handler: (service: GGLocatorLifecycleCallbacks) => void | undefined): void {
+        this._lifecycleHandler = handler;
+    }
+
+    public setWithLifecycle<T>(token: GGLocatorKey<T>, value: T, lifecycle: GGLocatorLifecycleCallbacks): void {
+        if (!this._lifecycleHandler) {
+            throw new Error("No lifecycle handler - are you registering outside compose phase?");
+        }
+        this.set(token, value);
+        this._lifecycleHandler(lifecycle);
+    }
+
+    // -----------
+
+    public setImmediate<R>(fn: () => R): NodeJS.Immediate {
+        return setImmediate(() => this.run(fn))
+    }
+
+    public setTimeout<R>(fn: () => R, timeout: number): NodeJS.Timeout {
+        return setTimeout(() => this.run(fn), timeout)
+    }
+
+    public setInterval<R>(fn: () => R, timeout: number): NodeJS.Timeout {
+        return setInterval(() => this.run(fn), timeout)
+    }
+
+    /**
+     * Wraps a function with a async context run() call. Safe for most cases.
+     * Consider wrapWithEnter in case you want same context for that function forever.
+     */
+    public wrapWithRun<T extends (...args: any[]) => any>(fn: T): T {
+        return ((...args: any[]) => {
+            return this.run(() => {
+                return fn(...args)
+            })
+        }) as T;
+    }
+
+    /**
+     * Wraps function to ensure this scope is active before each call.
+     * Unlike wrapWithRun, doesn't create a new async boundary - just ensures scope is entered.
+     * More performant for high-frequency event handlers where scope doesn't change.
+     */
+    public wrapWithEnter<T extends (...args: any[]) => any>(fn: T): T {
+        return ((...args: any[]) => {
+            this.ensureEntered()
+            return fn(...args)
+        }) as T;
+    }
+
+    public getScopeDebug(): GGLocatorScopeDebug {
+        const debug = new GGLocatorScopeDebug(this.name, this.creationStack);
+        this.values.forEach((value, name) => {
+            debug.add(name, value, this.registrationStacks.get(name));
+        })
+        return debug;
+    }
+
+    public getScopeDebugFull(list: GGLocatorScopeDebugList = new GGLocatorScopeDebugList()): GGLocatorScopeDebugList {
+        if (this.parent) {
+            this.parent.getScopeDebugFull(list);
+        }
+        list.add(this.getScopeDebug())
+        return list;
+    }
+
+    // -----------
+
+    public branch(name: string, serviceName?: string): GGLocatorScope {
+        return new GGLocatorScope(name, this, serviceName);
+    }
+
+    public run<R>(fn: () => R): R {
+        return GG_ASYNC_STORAGE.run(this, fn);
+    }
+
+    public enter() {
+        GG_ASYNC_STORAGE.enterWith(this);
+        return this;
+    }
+
+    public ensureEntered(): void {
+        const store = GG_ASYNC_STORAGE.getStore();
+        if (store !== this) {
+            GG_ASYNC_STORAGE.enterWith(this);
+        }
+    }
+
+    public reset(): void {
+        this.values.clear();
+        this.parent.values.forEach((value, name) => this.values.set(name, value))
+        this.registrationStacks.clear();
+        this.parent.registrationStacks.forEach((value, name) => this.registrationStacks.set(name, value))
+    }
+
+}
+
+/**
+ * Service initialization order - determines the sequence in which services start and stop.
+ * Services with lower values start first and stop last (reverse order for teardown).
+ *
+ * Example startup order: CONFIG → DATABASE → HTTP → INTL → BUSINESS → PERIODIC_JOBS → SERVICE_DISCOVERY
+ */
+export enum GGLocatorServiceType {
+    CONFIG = 0,
+    DATABASE = 10,
+    HTTP = 20,
+    INTL = 25,
+    BUSINESS = 30,
+    PERIODIC_JOBS = 40,
+    SERVICE_DISCOVERY = 999
+}
+
+/**
+ * Service lifecycle callbacks registered with GGServiceRegistry.
+ *
+ * Services register these during construction (in GGRuntime.compose) to participate
+ * in the runtime lifecycle - startup, teardown, and per-request context hooks.
+ */
+export interface GGLocatorLifecycleCallbacks {
+    type: GGLocatorServiceType
+    start: () => any | Promise<any>
+    teardown?: () => any | Promise<any>
+}

package/src/GGLocatorScopeDebug.ts

@@ -0,0 +1,153 @@
+// Console ANSI colors - defined inline to avoid circular dependency with @grest-ts/logger
+const LOG_COLORS = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    yellow: '\x1b[33m',
+    green: '\x1b[32m',
+    gray: '\x1b[90m',
+    magenta: '\x1b[35m',
+    blue: '\x1b[34m',
+};
+
+export interface GGLocatorDebugService {
+    key: string;
+    className: string | undefined;
+    stack: string[];
+    composeLine: string | undefined;
+}
+
+export interface GGLocatorRawServiceData {
+    key: string;
+    value: any;
+    rawStack: string[];
+}
+
+export class GGLocatorScopeDebugList {
+
+    public readonly scopes: GGLocatorScopeDebug[] = [];
+
+    public add(tree: GGLocatorScopeDebug) {
+        this.scopes.push(tree);
+    }
+
+    public toString(color: boolean = false): string {
+        return this.scopes.map(t => t.toString(color)).join("\n\n");
+    }
+
+    public toJSON(): object {
+        return {
+            scopes: this.scopes.map(s => s.toJSON())
+        };
+    }
+
+}
+
+export class GGLocatorScopeDebug {
+
+    public readonly scopeName: string;
+    public readonly creationStack: string[];
+    public readonly services: GGLocatorDebugService[] = [];
+
+    constructor(scopeName: string, rawCreationStack: string[]) {
+        this.scopeName = scopeName;
+        this.creationStack = this.processCreationStack(rawCreationStack);
+    }
+
+    private processCreationStack(rawStack: string[]): string[] {
+        return rawStack
+            .map(line => this.normalizeStackLine(line))
+            .filter((line): line is string => line !== undefined);
+    }
+
+    public add(key: string, value: any, rawStack: string[] | undefined): void {
+        this.services.push(this.processService({key: key, value, rawStack: rawStack ?? []}));
+    }
+
+    private processService(raw: GGLocatorRawServiceData): GGLocatorDebugService {
+        const className = raw.value?.constructor?.name;
+
+        // Find compose index and trim stack up to and including compose
+        const composeIndex = raw.rawStack.findIndex(line => line.includes('.compose'));
+        const trimmedStack = composeIndex >= 0
+            ? raw.rawStack.slice(0, composeIndex + 1)
+            : raw.rawStack;
+
+        return {
+            key: raw.key,
+            className: className !== 'Object' ? className : undefined,
+            stack: trimmedStack
+                .map(line => this.normalizeStackLine(line))
+                .filter((line): line is string => line !== undefined),
+            composeLine: this.findComposeLine(raw.rawStack)
+        };
+    }
+
+    private normalizeStackLine(line: string): string | undefined {
+        const trimmed = line.trim();
+        if (!trimmed) return undefined;
+
+        // Extract "at ClassName.method (file:line)" or just the location
+        const match = trimmed.match(/at\s+(.+)/);
+        const location = match ? match[1] : trimmed;
+        return this.normalizePathToFileUrl(location);
+    }
+
+    private findComposeLine(stack: string[]): string | undefined {
+        const composeLine = stack.find(line => line.includes('.compose'));
+        if (!composeLine) return undefined;
+        return this.normalizeStackLine(composeLine);
+    }
+
+    private normalizePathToFileUrl(location: string): string {
+        // Convert Windows paths to file:// URLs for better IDE support
+        // Matches: (C:\path\file.ts:10:5) or C:\path\file.ts:10:5
+        return location.replace(/([\w]:[\\/][^:)]+:\d+:\d+)/g, (path) => {
+            const normalizedPath = path.replace(/\\/g, '/');
+            return `file:///${normalizedPath}`;
+        });
+    }
+
+    public toString(color: boolean = false): string {
+        const C = color ? LOG_COLORS : {reset: "", bright: "", dim: "", cyan: "", yellow: "", green: "", gray: "", magenta: "", blue: ""};
+        const lines: string[] = [];
+
+        lines.push(`${C.bright}${C.cyan}Scope: ${this.scopeName}${C.reset}`);
+
+        if (this.creationStack.length > 0) {
+            lines.push(`\t${C.dim}Created at:${C.reset}`);
+            for (const frame of this.creationStack) {
+                lines.push(`\t\t${C.gray}${frame}${C.reset}`);
+            }
+        }
+
+        lines.push(`\t${C.dim}---${C.reset}`);
+
+        for (const service of this.services) {
+            const className = service.className ? `${C.dim} (${service.className})${C.reset}` : "";
+            lines.push(`\t${C.yellow}${service.key}${C.reset}${className}`);
+
+            if (service.composeLine) {
+                lines.push(`\t\t${C.green}compose: ${C.reset}${C.gray}${service.composeLine}${C.reset}`);
+            }
+
+            if (service.stack.length > 0) {
+                lines.push(`\t\t${C.dim}stack:${C.reset}`);
+                for (const frame of service.stack) {
+                    lines.push(`\t\t\t${C.gray}${frame}${C.reset}`);
+                }
+            }
+        }
+
+        return lines.join("\n");
+    }
+
+    public toJSON(): object {
+        return {
+            scopeName: this.scopeName,
+            creationStack: this.creationStack,
+            services: this.services
+        };
+    }
+}

package/src/GGLocatorStorage.ts

@@ -0,0 +1,9 @@
+import type {GGLocatorScope} from "./GGLocatorScope";
+import {BrowserAsyncStorage, type IAsyncStorage} from "@grest-ts/common";
+
+// Browser-safe by default. Node.js entry replaces with real AsyncLocalStorage.
+export let GG_ASYNC_STORAGE: IAsyncStorage<GGLocatorScope> = new BrowserAsyncStorage();
+
+export function _initLocatorStorage(storage: IAsyncStorage<GGLocatorScope>): void {
+    GG_ASYNC_STORAGE = storage;
+}

package/src/index-browser.ts

@@ -0,0 +1,4 @@
+export {GGLocatorScope, GGLocatorServiceType} from "./GGLocatorScope";
+export type {GGLocatorLifecycleCallbacks} from "./GGLocatorScope";
+export {GGLocatorKey} from "./GGLocatorKey";
+export {GGLocator} from "./GGLocator";

package/src/index-node.ts

@@ -0,0 +1,8 @@
+import {AsyncLocalStorage} from "node:async_hooks";
+import {_initLocatorStorage} from "./GGLocatorStorage";
+_initLocatorStorage(new AsyncLocalStorage());
+
+export {GGLocatorScope, GGLocatorServiceType} from "./GGLocatorScope";
+export type {GGLocatorLifecycleCallbacks} from "./GGLocatorScope";
+export {GGLocatorKey} from "./GGLocatorKey";
+export {GGLocator} from "./GGLocator";

package/src/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "//": "THIS FILE IS GENERATED - DO NOT EDIT",
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [
+      "node",
+      "vitest/globals"
+    ]
+  },
+  "include": [
+    "**/*"
+  ]
+}