@grest-ts/locator 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Grest Games OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# Locator Package (@grest-ts/locator)
+
+Service locator pattern implementation using AsyncLocalStorage for managing dependency injection in async contexts. Provides type-safe access to services throughout the request lifecycle without
+explicit passing.
+
+## When do you need it?
+
+- **Framework level**: The framework uses GGLocator internally to provide access to services like logging, config, databases, etc.
+- **Your services**: You can use it to avoid passing service dependencies through deep call stacks. Register once, access anywhere.
+
+Note: GGLocator is for **services** (long-lived dependencies). For request-scoped data (requestId, auth, etc.), use `GGContext` instead.
+
+## Basic Usage
+
+### Defining a Service Key
+
+```typescript
+import {GGLocatorKey} from "@grest-ts/locator"
+
+interface UserService {
+    getUser(id: string): Promise<User>
+}
+
+const UserServiceKey = new GGLocatorKey<UserService>("UserService")
+```
+
+### Case study: Dependency injection (DI) in Services
+
+Explicit, manually passing dependencies. This is what you probably would do for smaller services
+
+```typescript
+class OrderService {
+
+    private readonly userService: UserService
+    private readonly paymentService: PaymentService
+
+    constructor(userService: UserService, paymentService: PaymentService) {
+        this.userService = userService
+        this.paymentService = paymentService
+    }
+
+    async createOrder(userId: string, items: Item[]) {
+        const user = await this.userService.getUser(userId)
+        return this.paymentService.charge(user, items)
+    }
+}
+```
+
+Using dependency injection via GGLocator keys. Use this when things start getting bigger and you really see value in this.
+
+Pros: Less setup
+
+Cons: Less visibility for dependencies.
+
+```typescript
+class OrderService {
+
+    private readonly userService = UserServiceKey.get()
+    private readonly paymentService = PaymentServiceKey.get()
+
+    async createOrder(userId: string, items: Item[]) {
+        const user = await this.userService.getUser(userId)
+        return this.paymentService.charge(user, items)
+    }
+}
+```
+
+What NOT to do:
+
+```typescript
+class OrderService {
+
+    async createOrder(userId: string, items: Item[]) {
+        // VERY BAD: Keeps the dependency "hidden" and causes issues for your project in the future.
+        const user = await UserServiceKey.get().getUser(userId)
+        return PaymentServiceKey.get().charge(user, items)
+    }
+}
+```
+
+But when is direct access fine?
+
+You can always define that some "service" is generic and accessible everywhere. This is for you to decide where you draw the line.
+Passing Logging, metrics, tracing etc around everywhere can become very tedious, so it is easier to just use inline.
+
+```typescript
+class OrderService {
+
+    async createOrder(userId: string, items: Item[]) {
+        // Important - all these next examples are still async context scoped.
+        GGLog.info(this, "Some log message") // Library itself provides quick access is usually a hint it is meant to be used like this.
+        MyMetrics.orders.increment("orders.created") // Metrics are usually defined globally and accessible everywhere.
+        const isEnabled = MyConfig.something.somewhere.get() // Config is usually defined globally and accessible everywhere.
+    }
+}
+```
+
+### Registering and Accessing Services
+
+```typescript
+import {GGLocatorScope} from "@grest-ts/locator"
+
+// You usually don't need to create the scope, but for the completeness of this example, we create it here.
+new GGLocatorScope("something").run(async () => {
+
+    // Set the service
+    UserServiceKey.set(new UserServiceImpl())
+
+    // Set the service
+    UserServiceKey.overwrite(new UserServiceImpl())
+
+    // Access service anywhere in the call stack
+    const userService = UserServiceKey.get() // Throws if service is not set.
+    const user = await userService.getUser("123")
+
+    // Optionally get the service
+    const userServiceOpt = UserServiceKey.tryGet()
+    if (userServiceOpt) {
+        const user = await userServiceOpt.getUser("123")
+    }
+
+})
+```
+
+### Using GGLocator Static Helpers
+
+```typescript
+import {GGLocator} from "@grest-ts/locator"
+
+// Check if scope exists
+if (GGLocator.hasScope()) {
+    const scope = GGLocator.getScope()
+}
+
+// Safe access (returns undefined if no scope)
+const scope = GGLocator.tryGetScope()
+```
+
+## Debugging
+
+To see what services are registered in the current scope:
+
+```typescript
+const debugData = GGLocator.getScope().getScopeDebugFull();
+console.log(debugData.toString()) // Nicer for console log for a quick peek.
+console.log(debugData.toJSON()) // JSON format.
+```
+
+This prints the full scope tree with all registered services and their registration stacks - useful for understanding what's available in your current context.
+
+## Scope Branching
+
+Create child scopes that inherit parent services:
+
+```typescript
+const rootScope = new GGLocatorScope("root")
+rootScope.set(ConfigKey, config)
+
+// Child scope inherits parent services
+const requestScope = rootScope.branch("request")
+requestScope.set(RequestContextKey, requestContext)
+
+requestScope.run(() => {
+    ConfigKey.get()          // Works - inherited from parent
+    RequestContextKey.get()  // Works - set in this scope
+})
+```
+
+## GGLocatorKey Methods
+
+```typescript
+const ServiceKey = new GGLocatorKey<MyService>("MyService")
+
+// Get service (throws if not found)
+const service = ServiceKey.get()
+
+// Try get service (returns undefined if not found)
+const service = ServiceKey.tryGet()
+
+// Check if service exists
+if (ServiceKey.has()) { ...
+}
+
+// Set service (throws if already set)
+ServiceKey.set(new MyService())
+
+// Overwrite service (allows replacing)
+ServiceKey.overwrite(new MyService())
+```
+
+## Async Context Helpers
+
+Wrap callbacks to preserve scope across async boundaries:
+
+```typescript
+// Wrap function to run within current scope
+const wrappedFn = GGLocator.wrapWithRun(myCallback)
+
+// Schedule with scope preservation
+GGLocator.setTimeout(() => {
+    // Scope is preserved here
+    ServiceKey.get()
+}, 1000)
+
+GGLocator.setInterval(() => { ...
+}, 5000)
+GGLocator.setImmediate(() => { ...
+})
+```

package/dist/src/GGLocator.d.ts

@@ -0,0 +1,12 @@
+import { GGLocatorScope } from "./GGLocatorScope";
+export declare class GGLocator {
+    static hasScope(): boolean;
+    static getScope(): GGLocatorScope;
+    static tryGetScope(): GGLocatorScope | undefined;
+    static wrapWithRun<T extends (...args: any[]) => any>(fn: T): T;
+    static wrapWithEnter<T extends (...args: any[]) => any>(fn: T): T;
+    static setImmediate<R>(fn: () => R): NodeJS.Immediate;
+    static setTimeout<R>(fn: () => R, timeout: number): NodeJS.Timeout;
+    static setInterval<R>(fn: () => R, timeout: number): NodeJS.Timeout;
+}
+//# sourceMappingURL=GGLocator.d.ts.map

package/dist/src/GGLocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocator.d.ts","sourceRoot":"","sources":["../../src/GGLocator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAGhD,qBAAa,SAAS;WAEJ,QAAQ,IAAI,OAAO;WAInB,QAAQ,IAAI,cAAc;WAQ1B,WAAW,IAAI,cAAc,GAAG,SAAS;WAQzC,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC;WAIxD,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC;WAI1D,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS;WAI9C,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO;WAI3D,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO;CAI7E"}

package/dist/src/GGLocator.js

@@ -0,0 +1,35 @@
+import { GG_ASYNC_STORAGE } from "./GGLocatorStorage.js";
+export class GGLocator {
+    static hasScope() {
+        return GG_ASYNC_STORAGE.getStore() !== undefined;
+    }
+    static getScope() {
+        const level = GG_ASYNC_STORAGE.getStore();
+        if (!level) {
+            throw new Error(`No GGLocatorScope found! Make sure you have entered GGLocatorScope context.`);
+        }
+        return level;
+    }
+    static tryGetScope() {
+        return GG_ASYNC_STORAGE.getStore();
+    }
+    // ----------------------------------------------------
+    // Helper functions to make life easier :)
+    // ----------------------------------------------------
+    static wrapWithRun(fn) {
+        return this.getScope().wrapWithRun(fn);
+    }
+    static wrapWithEnter(fn) {
+        return this.getScope().wrapWithEnter(fn);
+    }
+    static setImmediate(fn) {
+        return this.getScope().setImmediate(fn);
+    }
+    static setTimeout(fn, timeout) {
+        return this.getScope().setTimeout(fn, timeout);
+    }
+    static setInterval(fn, timeout) {
+        return this.getScope().setInterval(fn, timeout);
+    }
+}
+//# sourceMappingURL=GGLocator.js.map

package/dist/src/GGLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocator.js","sourceRoot":"","sources":["../../src/GGLocator.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAEpD,MAAM,OAAO,SAAS;IAEX,MAAM,CAAC,QAAQ;QAClB,OAAO,gBAAgB,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC;IACrD,CAAC;IAEM,MAAM,CAAC,QAAQ;QAClB,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;QACnG,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAEM,MAAM,CAAC,WAAW;QACrB,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC;IACvC,CAAC;IAED,uDAAuD;IACvD,0CAA0C;IAC1C,uDAAuD;IAEhD,MAAM,CAAC,WAAW,CAAoC,EAAK;QAC9D,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAC3C,CAAC;IAEM,MAAM,CAAC,aAAa,CAAoC,EAAK;QAChE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IAEM,MAAM,CAAC,YAAY,CAAI,EAAW;QACrC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAC5C,CAAC;IAEM,MAAM,CAAC,UAAU,CAAI,EAAW,EAAE,OAAe;QACpD,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAEM,MAAM,CAAC,WAAW,CAAI,EAAW,EAAE,OAAe;QACrD,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;CAEJ"}

package/dist/src/GGLocatorKey.d.ts

@@ -0,0 +1,10 @@
+export declare class GGLocatorKey<T> {
+    readonly name: string;
+    constructor(name: string);
+    get(): T;
+    tryGet(): T | undefined;
+    has(): boolean;
+    set(value: T): void;
+    overwrite(value: T): void;
+}
+//# sourceMappingURL=GGLocatorKey.d.ts.map

package/dist/src/GGLocatorKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocatorKey.d.ts","sourceRoot":"","sources":["../../src/GGLocatorKey.ts"],"names":[],"mappings":"AAEA,qBAAa,YAAY,CAAC,CAAC;IAEvB,SAAgB,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM;IAIxB,GAAG,IAAI,CAAC;IAIR,MAAM,IAAI,CAAC,GAAG,SAAS;IAIvB,GAAG,IAAI,OAAO;IAId,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAInB,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;CAGnC"}

package/dist/src/GGLocatorKey.js

@@ -0,0 +1,23 @@
+import { GGLocator } from "./GGLocator.js";
+export class GGLocatorKey {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    get() {
+        return GGLocator.getScope().get(this);
+    }
+    tryGet() {
+        return GGLocator.tryGetScope()?.tryGet(this);
+    }
+    has() {
+        return !!GGLocator.tryGetScope()?.has(this);
+    }
+    set(value) {
+        GGLocator.getScope().set(this, value);
+    }
+    overwrite(value) {
+        GGLocator.getScope().overwrite(this, value);
+    }
+}
+//# sourceMappingURL=GGLocatorKey.js.map

package/dist/src/GGLocatorKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocatorKey.js","sourceRoot":"","sources":["../../src/GGLocatorKey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAEtC,MAAM,OAAO,YAAY;IAEL,IAAI,CAAQ;IAE5B,YAAmB,IAAY;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IACpB,CAAC;IAEM,GAAG;QACN,OAAO,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAEM,MAAM;QACT,OAAO,SAAS,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAEM,GAAG;QACN,OAAO,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAEM,GAAG,CAAC,KAAQ;QACf,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAEM,SAAS,CAAC,KAAQ;QACrB,SAAS,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC;CACJ"}

package/dist/src/GGLocatorScope.d.ts

@@ -0,0 +1,79 @@
+import type { GGLocatorKey } from "./GGLocatorKey";
+import { GGLocatorScopeDebug, GGLocatorScopeDebugList } from "./GGLocatorScopeDebug";
+type ConstructorOf<T> = new (...args: any[]) => T;
+/**
+ * service-locator pattern for async context cases.
+ */
+export declare class GGLocatorScope {
+    readonly name: string;
+    readonly serviceName?: string;
+    private readonly parent;
+    private readonly values;
+    private readonly registrationStacks;
+    private readonly creationStack;
+    constructor(name: string, parent?: GGLocatorScope, serviceName?: string);
+    private _get;
+    get<T>(token: GGLocatorKey<T>): T;
+    tryGet<T>(token: GGLocatorKey<T>): T | undefined;
+    getByTokenName<T>(name: string, type: ConstructorOf<T>): T;
+    set<T>(token: GGLocatorKey<T>, value: T): void;
+    overwrite<T>(token: GGLocatorKey<T>, value: T): void;
+    has<T>(token: GGLocatorKey<T>): boolean;
+    /**
+     * Returns all registered key names in this scope.
+     * Used by testkit to report available services to test runner.
+     */
+    getKeys(): string[];
+    private _lifecycleHandler?;
+    setLifecycleOwner(handler: (service: GGLocatorLifecycleCallbacks) => void | undefined): void;
+    setWithLifecycle<T>(token: GGLocatorKey<T>, value: T, lifecycle: GGLocatorLifecycleCallbacks): void;
+    setImmediate<R>(fn: () => R): NodeJS.Immediate;
+    setTimeout<R>(fn: () => R, timeout: number): NodeJS.Timeout;
+    setInterval<R>(fn: () => R, timeout: number): NodeJS.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.
+     */
+    wrapWithRun<T extends (...args: any[]) => any>(fn: T): 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.
+     */
+    wrapWithEnter<T extends (...args: any[]) => any>(fn: T): T;
+    getScopeDebug(): GGLocatorScopeDebug;
+    getScopeDebugFull(list?: GGLocatorScopeDebugList): GGLocatorScopeDebugList;
+    branch(name: string, serviceName?: string): GGLocatorScope;
+    run<R>(fn: () => R): R;
+    enter(): this;
+    ensureEntered(): void;
+    reset(): void;
+}
+/**
+ * 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 declare 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>;
+}
+export {};
+//# sourceMappingURL=GGLocatorScope.d.ts.map

package/dist/src/GGLocatorScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocatorScope.d.ts","sourceRoot":"","sources":["../../src/GGLocatorScope.ts"],"names":[],"mappings":"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"}

package/dist/src/GGLocatorScope.js

@@ -0,0 +1,160 @@
+import { GG_ASYNC_STORAGE } from "./GGLocatorStorage.js";
+import { GGLocatorScopeDebug, GGLocatorScopeDebugList } from "./GGLocatorScopeDebug.js";
+/**
+ * service-locator pattern for async context cases.
+ */
+export class GGLocatorScope {
+    name;
+    serviceName;
+    parent;
+    values;
+    registrationStacks;
+    creationStack;
+    constructor(name, parent, serviceName) {
+        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) ?? [];
+    }
+    _get(name) {
+        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;
+    }
+    get(token) {
+        return this._get(token.name);
+    }
+    tryGet(token) {
+        return this.values.get(token.name);
+    }
+    getByTokenName(name, type) {
+        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;
+    }
+    set(token, value) {
+        if (this.values.has(token.name)) {
+            throw new Error(`Scope already has service "${token.name}"!`);
+        }
+        this.overwrite(token, value);
+    }
+    overwrite(token, value) {
+        this.values.set(token.name, value);
+        this.registrationStacks.set(token.name, new Error().stack.split("\n").splice(2));
+    }
+    has(token) {
+        return this.values.has(token.name);
+    }
+    /**
+     * Returns all registered key names in this scope.
+     * Used by testkit to report available services to test runner.
+     */
+    getKeys() {
+        return Array.from(this.values.keys());
+    }
+    // -----------
+    _lifecycleHandler;
+    setLifecycleOwner(handler) {
+        this._lifecycleHandler = handler;
+    }
+    setWithLifecycle(token, value, lifecycle) {
+        if (!this._lifecycleHandler) {
+            throw new Error("No lifecycle handler - are you registering outside compose phase?");
+        }
+        this.set(token, value);
+        this._lifecycleHandler(lifecycle);
+    }
+    // -----------
+    setImmediate(fn) {
+        return setImmediate(() => this.run(fn));
+    }
+    setTimeout(fn, timeout) {
+        return setTimeout(() => this.run(fn), timeout);
+    }
+    setInterval(fn, 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.
+     */
+    wrapWithRun(fn) {
+        return ((...args) => {
+            return this.run(() => {
+                return fn(...args);
+            });
+        });
+    }
+    /**
+     * 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.
+     */
+    wrapWithEnter(fn) {
+        return ((...args) => {
+            this.ensureEntered();
+            return fn(...args);
+        });
+    }
+    getScopeDebug() {
+        const debug = new GGLocatorScopeDebug(this.name, this.creationStack);
+        this.values.forEach((value, name) => {
+            debug.add(name, value, this.registrationStacks.get(name));
+        });
+        return debug;
+    }
+    getScopeDebugFull(list = new GGLocatorScopeDebugList()) {
+        if (this.parent) {
+            this.parent.getScopeDebugFull(list);
+        }
+        list.add(this.getScopeDebug());
+        return list;
+    }
+    // -----------
+    branch(name, serviceName) {
+        return new GGLocatorScope(name, this, serviceName);
+    }
+    run(fn) {
+        return GG_ASYNC_STORAGE.run(this, fn);
+    }
+    enter() {
+        GG_ASYNC_STORAGE.enterWith(this);
+        return this;
+    }
+    ensureEntered() {
+        const store = GG_ASYNC_STORAGE.getStore();
+        if (store !== this) {
+            GG_ASYNC_STORAGE.enterWith(this);
+        }
+    }
+    reset() {
+        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 var GGLocatorServiceType;
+(function (GGLocatorServiceType) {
+    GGLocatorServiceType[GGLocatorServiceType["CONFIG"] = 0] = "CONFIG";
+    GGLocatorServiceType[GGLocatorServiceType["DATABASE"] = 10] = "DATABASE";
+    GGLocatorServiceType[GGLocatorServiceType["HTTP"] = 20] = "HTTP";
+    GGLocatorServiceType[GGLocatorServiceType["INTL"] = 25] = "INTL";
+    GGLocatorServiceType[GGLocatorServiceType["BUSINESS"] = 30] = "BUSINESS";
+    GGLocatorServiceType[GGLocatorServiceType["PERIODIC_JOBS"] = 40] = "PERIODIC_JOBS";
+    GGLocatorServiceType[GGLocatorServiceType["SERVICE_DISCOVERY"] = 999] = "SERVICE_DISCOVERY";
+})(GGLocatorServiceType || (GGLocatorServiceType = {}));
+//# sourceMappingURL=GGLocatorScope.js.map

package/dist/src/GGLocatorScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocatorScope.js","sourceRoot":"","sources":["../../src/GGLocatorScope.ts"],"names":[],"mappings":"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"}

package/dist/src/GGLocatorScopeDebug.d.ts

@@ -0,0 +1,32 @@
+export interface GGLocatorDebugService {
+    key: string;
+    className: string | undefined;
+    stack: string[];
+    composeLine: string | undefined;
+}
+export interface GGLocatorRawServiceData {
+    key: string;
+    value: any;
+    rawStack: string[];
+}
+export declare class GGLocatorScopeDebugList {
+    readonly scopes: GGLocatorScopeDebug[];
+    add(tree: GGLocatorScopeDebug): void;
+    toString(color?: boolean): string;
+    toJSON(): object;
+}
+export declare class GGLocatorScopeDebug {
+    readonly scopeName: string;
+    readonly creationStack: string[];
+    readonly services: GGLocatorDebugService[];
+    constructor(scopeName: string, rawCreationStack: string[]);
+    private processCreationStack;
+    add(key: string, value: any, rawStack: string[] | undefined): void;
+    private processService;
+    private normalizeStackLine;
+    private findComposeLine;
+    private normalizePathToFileUrl;
+    toString(color?: boolean): string;
+    toJSON(): object;
+}
+//# sourceMappingURL=GGLocatorScopeDebug.d.ts.map

package/dist/src/GGLocatorScopeDebug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GGLocatorScopeDebug.d.ts","sourceRoot":"","sources":["../../src/GGLocatorScopeDebug.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,qBAAqB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,GAAG,CAAC;IACX,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qBAAa,uBAAuB;IAEhC,SAAgB,MAAM,EAAE,mBAAmB,EAAE,CAAM;IAE5C,GAAG,CAAC,IAAI,EAAE,mBAAmB;IAI7B,QAAQ,CAAC,KAAK,GAAE,OAAe,GAAG,MAAM;IAIxC,MAAM,IAAI,MAAM;CAM1B;AAED,qBAAa,mBAAmB;IAE5B,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxC,SAAgB,QAAQ,EAAE,qBAAqB,EAAE,CAAM;gBAE3C,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE;IAKzD,OAAO,CAAC,oBAAoB;IAMrB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI;IAIzE,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,sBAAsB;IASvB,QAAQ,CAAC,KAAK,GAAE,OAAe,GAAG,MAAM;IAkCxC,MAAM,IAAI,MAAM;CAO1B"}