lanka 1.0.0

package/dist/_extend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/_internal/index.d.ts

@@ -0,0 +1,43 @@
+export { I as ILankaRuntime, T as TLankaRuntimeResolver, s as setLankaRuntimeResolver } from '../activeRuntime-FcsSJvUg.js';
+import '../ILankaScenarioVM-DuCyPoyT.js';
+import '../LankaScenarioLocator-BGQHwf3n.js';
+import '../ILankaScenarioMetadata-Bu-yggTZ.js';
+import '../ALankaGateway-ExlRGT3D.js';
+import '../lankaStandardValidator-CL-r-zEV.js';
+import '@standard-schema/spec';
+import '../LankaSharedStoreLocator-MvCpav5F.js';
+import '../ALankaSharedStore-B7uepuuk.js';
+import 'zustand/vanilla';
+import '../ILankaRuntimeConfig-Vl436GWK.js';
+import '../lankaHttpInFlight-Bk1eIuSx.js';
+import '../lankaRequestMiddleware-DAC5kCb7.js';
+
+declare function generateUuid(): string;
+
+/**
+ * Reads `key` from a record and returns it only if the value is a string.
+ * Returns `undefined` for missing or non-string values.
+ *
+ * Use when narrowing `Record<string, unknown>` payloads (SSE events,
+ * error response bodies, etc.) without `as` casts. Does NOT filter
+ * empty strings — callers that need non-empty values should check
+ * `.trim().length > 0` explicitly.
+ *
+ * Absorbed with {@link isRecord}, for the same reason.
+ */
+declare const getStringField: (data: Record<string, unknown>, key: string) => string | undefined;
+
+/**
+ * Type-guard: narrows `unknown` to `Record<string, unknown>`.
+ * Excludes `null`, primitives, and arrays-as-keys (arrays still satisfy
+ * `typeof === "object"`, but they're rarely the target — callers that need
+ * to exclude arrays should add `!Array.isArray(value)`).
+ *
+ * ABSORBED into this package when the layer was extracted: it lived in an
+ * application, and a package cannot import its consumer. An application
+ * re-exports this one rather than keeping a copy — two implementations of a
+ * three-line guard is how they end up disagreeing about `null`.
+ */
+declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+
+export { generateUuid, getStringField, isRecord };

package/dist/_internal/index.js

@@ -0,0 +1,34 @@
+import {
+  getStringField,
+  isRecord
+} from "../chunk-J5LA3Q6D.js";
+import {
+  setLankaRuntimeResolver
+} from "../chunk-BGVDPDX4.js";
+
+// src/_internal/generate-uuid/generateUuid.ts
+function generateUuid() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  let d = (/* @__PURE__ */ new Date()).getTime();
+  let d2 = typeof performance !== "undefined" && performance.now && performance.now() * 1e3 || 0;
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function(c) {
+    let r = Math.random() * 16;
+    if (d > 0) {
+      r = (d + r) % 16 | 0;
+      d = Math.floor(d / 16);
+    } else {
+      r = (d2 + r) % 16 | 0;
+      d2 = Math.floor(d2 / 16);
+    }
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+export {
+  generateUuid,
+  getStringField,
+  isRecord,
+  setLankaRuntimeResolver
+};
+//# sourceMappingURL=index.js.map

package/dist/_internal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/_internal/generate-uuid/generateUuid.ts"],"sourcesContent":["export function generateUuid() {\n\tif (typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\") {\n\t\treturn crypto.randomUUID();\n\t}\n\n\tlet d = new Date().getTime();\n\n\tlet d2 =\n\t\t(typeof performance !== \"undefined\" && performance.now && performance.now() * 1000) || 0;\n\n\treturn \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, function (c) {\n\t\tlet r = Math.random() * 16;\n\n\t\tif (d > 0) {\n\t\t\tr = ((d + r) % 16) | 0;\n\t\t\td = Math.floor(d / 16);\n\t\t} else {\n\t\t\tr = ((d2 + r) % 16) | 0;\n\t\t\td2 = Math.floor(d2 / 16);\n\t\t}\n\n\t\treturn (c === \"x\" ? r : (r & 0x3) | 0x8).toString(16);\n\t});\n}\n"],"mappings":";;;;;;;;;AAAO,SAAS,eAAe;AAC9B,MAAI,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe,YAAY;AAC7E,WAAO,OAAO,WAAW;AAAA,EAC1B;AAEA,MAAI,KAAI,oBAAI,KAAK,GAAE,QAAQ;AAE3B,MAAI,KACF,OAAO,gBAAgB,eAAe,YAAY,OAAO,YAAY,IAAI,IAAI,OAAS;AAExF,SAAO,uCAAuC,QAAQ,SAAS,SAAU,GAAG;AAC3E,QAAI,IAAI,KAAK,OAAO,IAAI;AAExB,QAAI,IAAI,GAAG;AACV,WAAM,IAAI,KAAK,KAAM;AACrB,UAAI,KAAK,MAAM,IAAI,EAAE;AAAA,IACtB,OAAO;AACN,WAAM,KAAK,KAAK,KAAM;AACtB,WAAK,KAAK,MAAM,KAAK,EAAE;AAAA,IACxB;AAEA,YAAQ,MAAM,MAAM,IAAK,IAAI,IAAO,GAAK,SAAS,EAAE;AAAA,EACrD,CAAC;AACF;","names":[]}

package/dist/activeRuntime-FcsSJvUg.d.ts

@@ -0,0 +1,84 @@
+import { L as LankaEventBusInstance, I as ILankaScenarioVM } from './ILankaScenarioVM-DuCyPoyT.js';
+import { c as LankaScenariosRegistry, b as LankaScenarioVMRegistry, L as LankaGatewayLocator, a as LankaScenarioLocator } from './LankaScenarioLocator-BGQHwf3n.js';
+import { b as ILankaRuntimeConfig } from './ILankaRuntimeConfig-Vl436GWK.js';
+import { I as ILankaInFlightCounter } from './lankaHttpInFlight-Bk1eIuSx.js';
+import { T as TLankaRequestMiddleware } from './lankaRequestMiddleware-DAC5kCb7.js';
+import { b as LankaSingletonLocator, L as LankaSharedStoreLocator } from './LankaSharedStoreLocator-MvCpav5F.js';
+
+/**
+ * The pointer to the framework instance that ambient facades resolve to.
+ *
+ * ## Why this module is separate and imports no value
+ *
+ * Framework state belongs to an instance (`createLanka`), but the callers of
+ * `lankaEventBus.dispatch`, `getLankaFlags()`, `lankaSingletons.foo`, `lankaHttpInFlight` —
+ * the ambient facades cannot hold one — a user-extended `ALankaScenario`, the
+ * static `LankaScenarioBootstrap` — so they ask which instance is active.
+ *
+ * The module is dependency-free DELIBERATELY: every import here is `import type`
+ * and disappears at compile time. Otherwise there would be a cycle
+ * `createLanka → locator → gateway → config → createLanka`, and module
+ * evaluation order would start deciding what ends up `undefined`.
+ *
+ * This is still a global pointer. Real isolation belongs to whoever holds an
+ * instance: their own bus, registries and counter. The facades serve ONE active
+ * instance — exactly what an application with one needs.
+ */
+interface ILankaRuntime {
+    readonly eventBus: LankaEventBusInstance;
+    readonly scenarios: LankaScenariosRegistry;
+    readonly viewModels: LankaScenarioVMRegistry;
+    readonly inFlight: ILankaInFlightCounter;
+    /**
+     * Request wrappers, in registration order: the first wraps them all.
+     *
+     * An array, not a set: order carries meaning — retry must sit outside request
+     * signing, or the second attempt goes out unsigned.
+     */
+    readonly requestMiddleware: readonly TLankaRequestMiddleware[];
+    /** Default response deadline. `undefined` means no limit. */
+    readonly requestTimeoutMs: number | undefined;
+    readonly locators: {
+        readonly gateways: LankaGatewayLocator;
+        readonly scenarios: LankaScenarioLocator;
+        readonly singletons: LankaSingletonLocator;
+        readonly sharedStores: LankaSharedStoreLocator;
+    };
+    readonly config: ILankaRuntimeConfig;
+    /**
+     * Bootstrap state of the scenario layer.
+     *
+     * A mutable object rather than contract fields: `LankaScenarioBootstrap` is an
+     * ambient facade and must write here without holding an instance.
+     */
+    readonly scenarioState: {
+        bootstrapped: boolean;
+        initialized: WeakSet<ILankaScenarioVM>;
+    };
+    setConfig(patch: ILankaRuntimeConfig): void;
+    getFlags(): NonNullable<ILankaRuntimeConfig["flags"]>;
+}
+/**
+ * How "which instance is active" is answered.
+ *
+ * A strategy, because the answer depends on where the code runs. In a browser
+ * there is one instance per document and a module-level pointer IS the answer. In
+ * a server process there is one instance per REQUEST, and a module-level pointer
+ * is the bug: the last request to start would answer for all of them.
+ */
+type TLankaRuntimeResolver = () => ILankaRuntime | null;
+/**
+ * Replaces the strategy, or restores the default one with `null`.
+ *
+ * The installed resolver is the WHOLE answer — the module-level pointer is not
+ * consulted behind it. That is deliberate: a fallback would turn "this ran
+ * outside a request" from a loud error into one request quietly reading another
+ * request's instance, which is the failure this seam exists to make impossible.
+ *
+ * Core ships no resolver and knows of none. What installs one is a package that
+ * knows the shape of a request; core knows only that the question has more than
+ * one answer.
+ */
+declare function setLankaRuntimeResolver(resolver: TLankaRuntimeResolver | null): void;
+
+export { type ILankaRuntime as I, type TLankaRuntimeResolver as T, setLankaRuntimeResolver as s };

package/dist/bootstrap/index.d.ts

@@ -0,0 +1,242 @@
+import { I as ILankaScope } from '../createLankaScope-Bc_vChRs.js';
+import { I as ILankaRuntime } from '../activeRuntime-FcsSJvUg.js';
+import { a as ILankaHost, I as ILankaFlags } from '../ILankaRuntimeConfig-Vl436GWK.js';
+import { T as TLankaRequestMiddleware } from '../lankaRequestMiddleware-DAC5kCb7.js';
+import '../LankaSharedStoreLocator-MvCpav5F.js';
+import '../ALankaSharedStore-B7uepuuk.js';
+import 'zustand/vanilla';
+import '../ILankaScenarioVM-DuCyPoyT.js';
+import '../LankaScenarioLocator-BGQHwf3n.js';
+import '../ILankaScenarioMetadata-Bu-yggTZ.js';
+import '../ALankaGateway-ExlRGT3D.js';
+import '../lankaStandardValidator-CL-r-zEV.js';
+import '@standard-schema/spec';
+import '../lankaHttpInFlight-Bk1eIuSx.js';
+
+/**
+ * A plugin is an extension core knows by SHAPE rather than by name.
+ *
+ * ## Plugin versus module
+ *
+ * A module is called by the application (`app → module`) and core does not know
+ * it exists. A plugin sits on the path core itself walks (`app → core → plugin`).
+ * The test question: does core need a hook for this to work? No — then it is a
+ * module, and making it a plugin costs more, because the hook has to be supported
+ * forever.
+ *
+ * ## Why `install` receives the instance
+ *
+ * So a plugin has no private route to the framework. Everything it can do comes
+ * from the instance it was given, which means two instances in one process (a
+ * test beside the app) do not share its configuration.
+ */
+interface ILankaPlugin {
+    /**
+     * The name the plugin is recognised by. Registering the same name twice is
+     * rejected: two copies of a retry policy would silently double the request
+     * count.
+     */
+    readonly name: string;
+    /**
+     * Installation. The returned function removes everything the plugin installed
+     * and is called when the plugin is removed and when the instance is disposed.
+     */
+    install: (lanka: ILankaInstance) => (() => void) | void;
+}
+
+/**
+ * A framework instance: all framework state in one object.
+ *
+ * What instance-scoped state buys: two apps in one process (micro-frontends,
+ * Storybook beside the app) no longer share a bus, locator caches and mock mode;
+ * SSR does not reuse state between different users' requests; and test isolation
+ * rests on construction rather than on a global `beforeEach` reaching into
+ * internal registries.
+ *
+ * **Ambient facades** — `lankaEventBus.dispatch`, `lankaSingletons.foo`,
+ * `getLankaFlags()`, `lankaHttpInFlight` — resolve THE ONE active instance
+ * (`internal/activeRuntime.ts`). Isolation belongs to whoever holds an instance;
+ * a facade cannot offer it.
+ *
+ * One thing stays at module level deliberately: `ALankaScenario` collects
+ * constructed scenarios into a static pool. That is a REGISTRY OF DEFINITIONS,
+ * not runtime state — the classes come from one `@lanka_di/Scenarios` barrel and
+ * both instances must see the same list. Splitting it would be divergence.
+ */
+interface ILankaInstance extends ILankaRuntime {
+    /**
+     * Adds a wrapper around every request. Returns a function that removes it.
+     *
+     * This is how `@lankajs/plugin-http` installs retry, the idempotency key, the
+     * CSRF header and auth refresh.
+     */
+    useRequestMiddleware(middleware: TLankaRequestMiddleware): () => void;
+    /** Default timeout for every request of this instance. */
+    setRequestTimeout(timeoutMs: number | undefined): void;
+    /** Resolves a service in the root scope — for the instance's whole lifetime. */
+    resolve<TInstance>(propertyName: string): TInstance;
+    /**
+     * Creates a scope: a lifetime shorter than the application's.
+     *
+     * An object created in a scope goes away with it.
+     */
+    createScope(): ILankaScope;
+    /**
+     * Registers a plugin. Returns a function that removes it.
+     *
+     * The fifth and last extension point. An extension point declared before
+     * anything plugs into it describes an imagined need while costing real
+     * support, so this one arrived with the FIRST plugin.
+     */
+    use(plugin: ILankaPlugin): () => void;
+    /** Runs services and the scenario layer. Idempotent. */
+    bootstrap(config?: ILankaBootstrapConfig): Promise<void>;
+    /** Has bootstrap already run? */
+    isBootstrapped(): boolean;
+    /** Makes this instance the one ambient facades resolve to. */
+    activate(): void;
+    /**
+     * Removes subscriptions, clears registries and, if this instance was active,
+     * clears the pointer. Returns the framework to its pre-bootstrap state.
+     */
+    dispose(): void;
+}
+interface ILankaInstanceConfig {
+    host: ILankaHost;
+    flags?: ILankaFlags;
+}
+interface ILankaServiceConfig {
+    name?: string;
+    init: () => void | Promise<void>;
+    sync?: boolean;
+    priority?: number;
+    /**
+     * A failure of this service does not abort bootstrap.
+     *
+     * Without the flag one failed service takes the WHOLE phase with it: the async
+     * phase because of `Promise.all`, the sync phase because later tasks never run.
+     * Wrapping the failure in a swallowing `try/catch` is worse still — the app
+     * starts with a partially executed plan and does not know it.
+     */
+    optional?: boolean;
+    /**
+     * How long to wait for the service. Overrunning counts as a failure.
+     *
+     * Without a deadline a service that never settles holds bootstrap forever and
+     * the app never paints its first screen. Failing is more honest than waiting:
+     * an optional service is skipped, a required one names itself.
+     */
+    timeoutMs?: number;
+}
+interface ILankaScenarioBootstrapConfig {
+    sync?: boolean;
+    priority?: number;
+}
+interface ILankaBootstrapConfig {
+    services?: ILankaServiceConfig[];
+    scenarios?: ILankaScenarioBootstrapConfig;
+}
+/**
+ * Creates an instance and makes it active.
+ *
+ * Activating on creation is the deliberate default: there is almost always one
+ * app and the facades must work immediately. A second instance takes the
+ * pointer — the last one created serves the facades. Callers needing another
+ * order call `activate()` explicitly.
+ */
+declare function createLanka(config: ILankaInstanceConfig): ILankaInstance;
+
+/** What `startLanka` takes beyond the host, all of it optional. */
+interface ILankaStartOptions {
+    flags?: ILankaFlags;
+    /** Installed before bootstrap, in the order given. */
+    plugins?: readonly ILankaPlugin[];
+    services?: ILankaServiceConfig[];
+    scenarios?: ILankaBootstrapConfig["scenarios"];
+}
+/**
+ * A whole host, or the pieces of one — but not both.
+ *
+ * A union rather than three optional fields, so passing `host` AND `apiBaseUrl`
+ * is a compile error rather than a silent precedence rule somebody has to look
+ * up. Passing neither is fine: an application served from its API's origin, or
+ * one whose gateways write whole URLs, has nothing to say here.
+ */
+type TLankaStartConfig = ILankaStartOptions & ({
+    host: ILankaHost;
+    apiBaseUrl?: never;
+    messages?: never;
+} | {
+    host?: never;
+    /** A prefix for every path a gateway builds. Empty by default. */
+    apiBaseUrl?: string;
+    /** Anything but the base URL, when English is not good enough. */
+    messages?: Partial<Omit<ILankaHost, "apiBaseUrl">>;
+});
+
+/**
+ * A started framework, in one call.
+ *
+ * ```ts
+ * const lanka = await startLanka({ apiBaseUrl: "https://api.example.com" });
+ * const sameOrigin = await startLanka(); // nothing to configure yet
+ * ```
+ *
+ * ## What it saves, and what it does not hide
+ *
+ * `createLanka` already activates the instance it returns, and `bootstrap` already
+ * brings up the scenario layer — so an application's whole start-up was two calls
+ * and a `for` loop over its plugins. This is those, in the order that works, and
+ * nothing else: what comes back is the same `ILankaInstance`, with every method
+ * it always had.
+ *
+ * The order matters and is the reason this exists rather than a paragraph in a
+ * guide. Plugins install BEFORE bootstrap, because a plugin that adds a
+ * bootstrap service after the plan is built adds it to nothing; and bootstrap is
+ * awaited, because a screen rendered against a half-started framework fails in
+ * the layer it reaches first rather than where the mistake was.
+ *
+ * An application that needs something between those steps — registering a
+ * singleton whose construction reads a service's result, say — writes the two
+ * calls out and keeps this one for the next project.
+ */
+declare const startLanka: (config?: TLankaStartConfig) => Promise<ILankaInstance>;
+
+/**
+ * Resets the active instance, if there is one.
+ *
+ * What the test kit needs between cases. Silent when there is no instance:
+ * "reset nothing" is not an error, and the setup file runs before EVERY test,
+ * including those that never bootstrap the framework.
+ */
+declare function resetActiveLanka(): void;
+
+/**
+ * A plugin, written as a class.
+ *
+ * The functional style is a function returning `{ name, install }`, and it is
+ * what the framework's own five plugins use — a plugin is a value handed to
+ * `use()`, and the ecosystem writes those as `react()`, `pinia()`,
+ * `tsconfigPaths()`.
+ *
+ * This is the same contract for an application that keeps its plugins as
+ * classes: `name` is a field, `install` is a method, and `uninstall` is the
+ * teardown the framework calls on removal and on dispose. Nothing above can
+ * tell which style wrote it — `use()` sees `ILankaPlugin` either way.
+ */
+declare abstract class ALankaPlugin implements ILankaPlugin {
+    abstract readonly name: string;
+    /** Everything this plugin puts in place. Return nothing if there is nothing to undo. */
+    protected abstract onInstall(lanka: ILankaInstance): void;
+    /**
+     * Removes what `onInstall` put in place.
+     *
+     * A default that does nothing rather than an abstract member: an abstract one
+     * would break every existing subclass the day it was added, and most plugins
+     * genuinely have nothing to undo.
+     */
+    protected onUninstall(): void;
+    install(lanka: ILankaInstance): () => void;
+}
+
+export { ALankaPlugin, type ILankaBootstrapConfig, type ILankaInstance, type ILankaInstanceConfig, type ILankaPlugin, type ILankaScenarioBootstrapConfig, ILankaScope, type ILankaServiceConfig, type ILankaStartOptions, type TLankaStartConfig, createLanka, resetActiveLanka, startLanka };

package/dist/bootstrap/index.js

@@ -0,0 +1,22 @@
+import {
+  ALankaPlugin,
+  createLanka,
+  resetActiveLanka,
+  startLanka
+} from "../chunk-RYFZCAQ3.js";
+import "../chunk-Q3SOVBIJ.js";
+import "../chunk-FIR4XTBL.js";
+import "../chunk-EWVDJYCC.js";
+import "../chunk-XESL274R.js";
+import "../chunk-UJEC7H6K.js";
+import "../chunk-ILQNYQY5.js";
+import "../chunk-C2HP7CRD.js";
+import "../chunk-D27MREPB.js";
+import "../chunk-BGVDPDX4.js";
+export {
+  ALankaPlugin,
+  createLanka,
+  resetActiveLanka,
+  startLanka
+};
+//# sourceMappingURL=index.js.map

package/dist/bootstrap/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-73IVH3C6.js

@@ -0,0 +1,52 @@
+import {
+  getStringField,
+  isRecord
+} from "./chunk-J5LA3Q6D.js";
+import {
+  LankaError
+} from "./chunk-Q7QESSYF.js";
+import {
+  getLankaHost
+} from "./chunk-RKYKK6MN.js";
+
+// src/errors/_factories/create-lanka-api-error/createLankaApiError.ts
+var createLankaApiError = (status, errors, body) => {
+  const errorMessage = errors.length > 0 && errors[0] ? errors[0] : getLankaHost().httpErrorMessage(status);
+  return new LankaError({
+    kind: "http",
+    message: errorMessage,
+    status,
+    issues: errors.length > 0 ? errors : [errorMessage],
+    body
+  });
+};
+
+// src/errors/handle-lanka-api-error/handleLankaApiError.ts
+var RAW_TEXT_LIMIT = 200;
+var nonEmpty = (body, key) => {
+  const value = getStringField(body, key);
+  return value !== void 0 && value.trim().length > 0 ? value.trim() : void 0;
+};
+var handleLankaApiError = async (response) => {
+  const raw = await response.clone().text().catch(() => "");
+  let body;
+  if (raw.trim().length > 0) {
+    try {
+      body = JSON.parse(raw);
+    } catch {
+      body = void 0;
+    }
+  }
+  const message = (isRecord(body) ? nonEmpty(body, "message") : void 0) ?? (body === void 0 && raw.trim().length > 0 ? raw.trim().slice(0, RAW_TEXT_LIMIT) : void 0);
+  throw createLankaApiError(
+    response.status,
+    message ? [message] : [getLankaHost().httpErrorMessage(response.status)],
+    body
+  );
+};
+
+export {
+  createLankaApiError,
+  handleLankaApiError
+};
+//# sourceMappingURL=chunk-73IVH3C6.js.map

package/dist/chunk-73IVH3C6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/_factories/create-lanka-api-error/createLankaApiError.ts","../src/errors/handle-lanka-api-error/handleLankaApiError.ts"],"sourcesContent":["import { getLankaHost } from \"../../../config/get-lanka-host/getLankaHost\";\nimport { LankaError } from \"../../lanka-error/LankaError\";\n\n/**\n * A server failure, named by kind.\n *\n * `http`, not `domain`: core sees only the status and the text. The domain\n * failure code — what the application branches on — is extracted from the body by\n * `@lankajs/plugin-http`, because body formats differ per backend and that is\n * policy, not framework.\n */\nexport const createLankaApiError = (\n\tstatus: number,\n\terrors: string[],\n\tbody?: unknown,\n): LankaError => {\n\tconst errorMessage =\n\t\terrors.length > 0 && errors[0] ? errors[0] : getLankaHost().httpErrorMessage(status);\n\n\treturn new LankaError({\n\t\tkind: \"http\",\n\t\tmessage: errorMessage,\n\t\tstatus,\n\t\tissues: errors.length > 0 ? errors : [errorMessage],\n\t\tbody,\n\t});\n};\n","import { isRecord } from \"../../_internal/_guards/isRecord\";\nimport { getStringField } from \"../../_internal/_guards/getStringField\";\nimport { getLankaHost } from \"../../config/get-lanka-host/getLankaHost\";\nimport { createLankaApiError } from \"../_factories/create-lanka-api-error/createLankaApiError\";\n\n/** The length past which foreign text in a message stops helping. */\nconst RAW_TEXT_LIMIT = 200;\n\nconst nonEmpty = (body: Record<string, unknown>, key: string): string | undefined => {\n\tconst value = getStringField(body, key);\n\treturn value !== undefined && value.trim().length > 0 ? value.trim() : undefined;\n};\n\n/**\n * Normalises ANY unsuccessful response into a `LankaError`.\n *\n * Core does three things: reads the body once, takes `message` from it when it is\n * a string, and attaches the parsed body to the error. That is all.\n *\n * It parses no shapes. Body formats differ per backend, and a framework that\n * knows several knows none — it guesses. Parsing lives in `@lankajs/plugin-http`,\n * where it is configurable; the body travels with the error (`error.body`), so\n * the plugin parses it WITHOUT a second read of the `Response`, which is\n * impossible anyway: a stream is read once.\n *\n * ## Why an unparsed body is `http`, not `schema`\n *\n * The distinction carries a decision. `schema` means \"the response is the wrong\n * shape\" — the contract is broken and retrying is pointless. An ERROR body that\n * could not be parsed is not a broken contract: the server refused deliberately\n * and simply described it differently than expected.\n */\nexport const handleLankaApiError = async (response: Response): Promise<never> => {\n\tconst raw = await response\n\t\t.clone()\n\t\t.text()\n\t\t.catch(() => \"\");\n\n\tlet body: unknown;\n\tif (raw.trim().length > 0) {\n\t\ttry {\n\t\t\tbody = JSON.parse(raw);\n\t\t} catch {\n\t\t\t// A body that is not JSON is still the only description of the failure\n\t\t\t// there is, so it becomes the message rather than being discarded for\n\t\t\t// having the wrong shape.\n\t\t\tbody = undefined;\n\t\t}\n\t}\n\n\tconst message =\n\t\t(isRecord(body) ? nonEmpty(body, \"message\") : undefined) ??\n\t\t(body === undefined && raw.trim().length > 0\n\t\t\t? raw.trim().slice(0, RAW_TEXT_LIMIT)\n\t\t\t: undefined);\n\n\tthrow createLankaApiError(\n\t\tresponse.status,\n\t\tmessage ? [message] : [getLankaHost().httpErrorMessage(response.status)],\n\t\tbody,\n\t);\n};\n"],"mappings":";;;;;;;;;;;;AAWO,IAAM,sBAAsB,CAClC,QACA,QACA,SACgB;AAChB,QAAM,eACL,OAAO,SAAS,KAAK,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,aAAa,EAAE,iBAAiB,MAAM;AAEpF,SAAO,IAAI,WAAW;AAAA,IACrB,MAAM;AAAA,IACN,SAAS;AAAA,IACT;AAAA,IACA,QAAQ,OAAO,SAAS,IAAI,SAAS,CAAC,YAAY;AAAA,IAClD;AAAA,EACD,CAAC;AACF;;;ACpBA,IAAM,iBAAiB;AAEvB,IAAM,WAAW,CAAC,MAA+B,QAAoC;AACpF,QAAM,QAAQ,eAAe,MAAM,GAAG;AACtC,SAAO,UAAU,UAAa,MAAM,KAAK,EAAE,SAAS,IAAI,MAAM,KAAK,IAAI;AACxE;AAqBO,IAAM,sBAAsB,OAAO,aAAuC;AAChF,QAAM,MAAM,MAAM,SAChB,MAAM,EACN,KAAK,EACL,MAAM,MAAM,EAAE;AAEhB,MAAI;AACJ,MAAI,IAAI,KAAK,EAAE,SAAS,GAAG;AAC1B,QAAI;AACH,aAAO,KAAK,MAAM,GAAG;AAAA,IACtB,QAAQ;AAIP,aAAO;AAAA,IACR;AAAA,EACD;AAEA,QAAM,WACJ,SAAS,IAAI,IAAI,SAAS,MAAM,SAAS,IAAI,YAC7C,SAAS,UAAa,IAAI,KAAK,EAAE,SAAS,IACxC,IAAI,KAAK,EAAE,MAAM,GAAG,cAAc,IAClC;AAEJ,QAAM;AAAA,IACL,SAAS;AAAA,IACT,UAAU,CAAC,OAAO,IAAI,CAAC,aAAa,EAAE,iBAAiB,SAAS,MAAM,CAAC;AAAA,IACvE;AAAA,EACD;AACD;","names":[]}

package/dist/chunk-BGVDPDX4.js

@@ -0,0 +1,29 @@
+// src/_internal/active-runtime/activeRuntime.ts
+var active = null;
+var resolveRuntime = null;
+function setActiveRuntime(runtime) {
+  active = runtime;
+}
+function setLankaRuntimeResolver(resolver) {
+  resolveRuntime = resolver;
+}
+function getActiveRuntime() {
+  return resolveRuntime ? resolveRuntime() : active;
+}
+function requireActiveRuntime() {
+  const runtime = resolveRuntime ? resolveRuntime() : active;
+  if (!runtime) {
+    throw new Error(
+      resolveRuntime ? "lanka has no instance for this call. A runtime resolver is installed and answered with none, which on a server means the code ran outside a request scope \u2014 start one, or do this work inside it." : "lanka used before an instance existed. Call createLanka({ host }) and activate it."
+    );
+  }
+  return runtime;
+}
+
+export {
+  setActiveRuntime,
+  setLankaRuntimeResolver,
+  getActiveRuntime,
+  requireActiveRuntime
+};
+//# sourceMappingURL=chunk-BGVDPDX4.js.map

package/dist/chunk-BGVDPDX4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/_internal/active-runtime/activeRuntime.ts"],"sourcesContent":["import type { LankaEventBusInstance } from \"../../scenario/event-bus/lanka-event-bus-instance/LankaEventBusInstance\";\nimport type { LankaScenariosRegistry } from \"../../scenario/_registries/lanka-scenarios-registry/LankaScenariosRegistry\";\nimport type { LankaScenarioVMRegistry } from \"../../scenario/_registries/lanka-scenario-vm-registry/LankaScenarioVMRegistry\";\nimport type { ILankaRuntimeConfig } from \"../../config/_interfaces/ILankaRuntimeConfig\";\nimport type { ILankaInFlightCounter } from \"../../gateway/inflight/lankaHttpInFlight\";\nimport type { ILankaScenarioVM } from \"../../scenario/_interfaces/ILankaScenarioVM\";\nimport type { TLankaRequestMiddleware } from \"../../gateway/request/lankaRequestMiddleware\";\nimport type { LankaGatewayLocator } from \"../../locator/gateway/lanka-gateway-locator/LankaGatewayLocator\";\nimport type { LankaScenarioLocator } from \"../../locator/scenario/lanka-scenario-locator/LankaScenarioLocator\";\nimport type { LankaSingletonLocator } from \"../../locator/singleton/lanka-singleton-locator/LankaSingletonLocator\";\nimport type { LankaSharedStoreLocator } from \"../../locator/shared-store/lanka-shared-store-locator/LankaSharedStoreLocator\";\n\n/**\n * The pointer to the framework instance that ambient facades resolve to.\n *\n * ## Why this module is separate and imports no value\n *\n * Framework state belongs to an instance (`createLanka`), but the callers of\n * `lankaEventBus.dispatch`, `getLankaFlags()`, `lankaSingletons.foo`, `lankaHttpInFlight` —\n * the ambient facades cannot hold one — a user-extended `ALankaScenario`, the\n * static `LankaScenarioBootstrap` — so they ask which instance is active.\n *\n * The module is dependency-free DELIBERATELY: every import here is `import type`\n * and disappears at compile time. Otherwise there would be a cycle\n * `createLanka → locator → gateway → config → createLanka`, and module\n * evaluation order would start deciding what ends up `undefined`.\n *\n * This is still a global pointer. Real isolation belongs to whoever holds an\n * instance: their own bus, registries and counter. The facades serve ONE active\n * instance — exactly what an application with one needs.\n */\nexport interface ILankaRuntime {\n\treadonly eventBus: LankaEventBusInstance;\n\treadonly scenarios: LankaScenariosRegistry;\n\treadonly viewModels: LankaScenarioVMRegistry;\n\treadonly inFlight: ILankaInFlightCounter;\n\t/**\n\t * Request wrappers, in registration order: the first wraps them all.\n\t *\n\t * An array, not a set: order carries meaning — retry must sit outside request\n\t * signing, or the second attempt goes out unsigned.\n\t */\n\treadonly requestMiddleware: readonly TLankaRequestMiddleware[];\n\t/** Default response deadline. `undefined` means no limit. */\n\treadonly requestTimeoutMs: number | undefined;\n\treadonly locators: {\n\t\treadonly gateways: LankaGatewayLocator;\n\t\treadonly scenarios: LankaScenarioLocator;\n\t\treadonly singletons: LankaSingletonLocator;\n\t\treadonly sharedStores: LankaSharedStoreLocator;\n\t};\n\treadonly config: ILankaRuntimeConfig;\n\t/**\n\t * Bootstrap state of the scenario layer.\n\t *\n\t * A mutable object rather than contract fields: `LankaScenarioBootstrap` is an\n\t * ambient facade and must write here without holding an instance.\n\t */\n\treadonly scenarioState: {\n\t\tbootstrapped: boolean;\n\t\tinitialized: WeakSet<ILankaScenarioVM>;\n\t};\n\tsetConfig(patch: ILankaRuntimeConfig): void;\n\tgetFlags(): NonNullable<ILankaRuntimeConfig[\"flags\"]>;\n}\n\n/**\n * How \"which instance is active\" is answered.\n *\n * A strategy, because the answer depends on where the code runs. In a browser\n * there is one instance per document and a module-level pointer IS the answer. In\n * a server process there is one instance per REQUEST, and a module-level pointer\n * is the bug: the last request to start would answer for all of them.\n */\nexport type TLankaRuntimeResolver = () => ILankaRuntime | null;\n\nlet active: ILankaRuntime | null = null;\nlet resolveRuntime: TLankaRuntimeResolver | null = null;\n\nexport function setActiveRuntime(runtime: ILankaRuntime | null): void {\n\tactive = runtime;\n}\n\n/**\n * Replaces the strategy, or restores the default one with `null`.\n *\n * The installed resolver is the WHOLE answer — the module-level pointer is not\n * consulted behind it. That is deliberate: a fallback would turn \"this ran\n * outside a request\" from a loud error into one request quietly reading another\n * request's instance, which is the failure this seam exists to make impossible.\n *\n * Core ships no resolver and knows of none. What installs one is a package that\n * knows the shape of a request; core knows only that the question has more than\n * one answer.\n */\nexport function setLankaRuntimeResolver(resolver: TLankaRuntimeResolver | null): void {\n\tresolveRuntime = resolver;\n}\n\nexport function getActiveRuntime(): ILankaRuntime | null {\n\treturn resolveRuntime ? resolveRuntime() : active;\n}\n\n/**\n * The active instance, or a loud failure.\n *\n * No fallback, deliberately, for the same reason `getLankaHost` has none: an\n * instance created silently on the fly would mean subscriptions went to one bus\n * and events to another, and the divergence would surface three layers away.\n */\nexport function requireActiveRuntime(): ILankaRuntime {\n\t// The strategy is read here rather than through `getActiveRuntime()`: this is\n\t// the hottest path in the framework — every ambient facade, every request,\n\t// every dispatch — and a call that only forwards is a call that shows up in\n\t// `perf/`.\n\tconst runtime = resolveRuntime ? resolveRuntime() : active;\n\n\tif (!runtime) {\n\t\tthrow new Error(\n\t\t\tresolveRuntime\n\t\t\t\t? \"lanka has no instance for this call. A runtime resolver is installed and \" +\n\t\t\t\t\t\t\"answered with none, which on a server means the code ran outside a \" +\n\t\t\t\t\t\t\"request scope — start one, or do this work inside it.\"\n\t\t\t\t: \"lanka used before an instance existed. Call createLanka({ host }) and \" +\n\t\t\t\t\t\t\"activate it.\",\n\t\t);\n\t}\n\n\treturn runtime;\n}\n"],"mappings":";AA4EA,IAAI,SAA+B;AACnC,IAAI,iBAA+C;AAE5C,SAAS,iBAAiB,SAAqC;AACrE,WAAS;AACV;AAcO,SAAS,wBAAwB,UAA8C;AACrF,mBAAiB;AAClB;AAEO,SAAS,mBAAyC;AACxD,SAAO,iBAAiB,eAAe,IAAI;AAC5C;AASO,SAAS,uBAAsC;AAKrD,QAAM,UAAU,iBAAiB,eAAe,IAAI;AAEpD,MAAI,CAAC,SAAS;AACb,UAAM,IAAI;AAAA,MACT,iBACG,2MAGA;AAAA,IAEJ;AAAA,EACD;AAEA,SAAO;AACR;","names":[]}