@reactra/service 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akhil Shastri and the Reactra contributors
+
+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,17 @@
+# @reactra/service
+
+> Reactra service/DI runtime — dependency injection for Reactra apps.
+
+**Alpha** — published under the npm dist-tag `alpha`. APIs may change before 1.0.
+
+```bash
+npm install @reactra/service@alpha
+```
+
+Part of [Reactra](https://github.com/akhilshastri/reactra) — a compiler-first,
+React-19-compatible framework. See the [documentation](https://reactra-docs.vercel.app) to get
+started.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Per-service runtime instance — the object the factory returns. Method
+ * names are the keys; values are plain (async or sync) functions. Services
+ * are stateless callable units per Service spec §1, so there is no
+ * subscribe/notify/snapshot — they expose methods only.
+ */
+export type ServiceInstance = Record<string, unknown>;
+/**
+ * The shape a compiler-emitted service binding takes: a `{ name, factory }`
+ * tuple the user passes to `configureServices`. The factory is invoked
+ * eagerly at registration time so service-to-service `inject` lookups
+ * resolve in declaration order (the user lists dependencies first in the
+ * `configureServices` call).
+ */
+export interface ServiceBinding {
+    name: string;
+    factory: () => ServiceInstance;
+    /**
+     * Wave 3 §2b — `export service scoped X { ... }`. When `true`, the
+     * binding is REGISTERED at `configureServices` time but NOT
+     * instantiated. The instance is created on
+     * `ServiceRegistry.activateScopedServices()` (typically wired to
+     * `RouterRegistry`'s setLocation via `bindScopedServicesToRouter`) and
+     * disposed on the next `deactivateScopedServices` call — invoking
+     * `instance.dispose()` if the surface includes a `dispose` method.
+     * Absent / `false` for app-singleton bindings (the default).
+     */
+    scoped?: boolean;
+}
+declare class ServiceRegistryImpl {
+    private instances;
+    private scopedFactories;
+    /**
+     * Register a service binding. App-singleton (`scoped !== true`) is
+     * instantiated immediately so downstream services can resolve
+     * dependencies via `ServiceRegistry.get` during their own factory
+     * call. Scoped bindings (Wave 3 §2b) store the factory only — they
+     * spin up on `activateScopedServices()`.
+     */
+    register: (binding: ServiceBinding) => void;
+    /**
+     * Wave 3 §2b — instantiate every scoped service. Idempotent: a
+     * second activation without intervening deactivate is a no-op for
+     * services that already have a live instance (the user might call
+     * this twice on a route re-entry). Called by the router-bound
+     * lifecycle hook in `bindScopedServicesToRouter`; safe to call
+     * manually in tests.
+     */
+    activateScopedServices: () => void;
+    /**
+     * Wave 3 §2b — dispose + drop every scoped service instance. For
+     * each scoped instance with a `dispose()` method, invokes it before
+     * deletion. Errors thrown by `dispose` are caught + console.error'd
+     * so a single misbehaving service can't block the next route's
+     * activation. Singleton instances are unaffected.
+     */
+    deactivateScopedServices: () => void;
+    /**
+     * Look up a singleton by name. Throws if the service wasn't registered —
+     * usually means the user forgot to add it to `configureServices`, or
+     * listed it after a consumer in the same array.
+     */
+    get: <T extends ServiceInstance = ServiceInstance>(name: string) => T;
+    /** True if a service is registered. Used by tests + future provide wiring. */
+    has: (name: string) => boolean;
+    /**
+     * HMR hot-replace a binding (Compiler §5.3). Compiler-emitted
+     * `import.meta.hot.accept(...)` blocks in service-bearing files call
+     * this after the module re-evaluates so the new factory takes effect
+     * without a full page reload.
+     *
+     * Services are stateless callable units (Service spec §1) so the
+     * replace is just an instance swap. Consumers that cached a reference
+     * via `inject X` at component-body top see the stale singleton until
+     * their own component re-renders (component-side Fast Refresh in the
+     * consumer file, or the next interaction). Phase-1 trade-off; matches
+     * the store-replace one-render-delay characteristic.
+     *
+     * Idempotent on an unknown name (treated as a fresh register).
+     */
+    replace: (binding: ServiceBinding) => void;
+}
+/**
+ * The process-wide service registry singleton. The compiler emits imports
+ * of this and `ServiceRegistry.get("X")` at every `inject X` site. User
+ * code typically doesn't touch it directly except through `configureServices`.
+ */
+export declare const ServiceRegistry: ServiceRegistryImpl;
+/**
+ * Bootstrap call — invoked from `src/main.tsx` per Runtime v0 §5. Registers
+ * every service binding the app cares about. Order matters: a service must
+ * appear in this array after the services it injects, because each
+ * factory call resolves `inject` references eagerly via `ServiceRegistry.get`.
+ */
+export declare const configureServices: (opts: {
+    services: ServiceBinding[];
+}) => void;
+/**
+ * Compiler-emitted factories call this to build a `ServiceInstance`. The
+ * `build` callback returns the surface object — `{ methodName: fn, ... }`.
+ * This helper exists for symmetry with `createStoreInstance` and to leave a
+ * future hook for Strategy B context-wrapping; today it is a pass-through.
+ *
+ * Shape used by emitted code (see Pass 9 codegen):
+ *
+ *   createServiceInstance(() => {
+ *     const authService = ServiceRegistry.get("authService")
+ *     const get = async (id) => { ... authService.getToken() ... }
+ *     return { get }
+ *   })
+ */
+export declare const createServiceInstance: (build: () => ServiceInstance) => ServiceInstance;
+/**
+ * The per-subtree map of service overrides. Read by {@link useService};
+ * written by the compiler-emitted `<ServiceContext.Provider>` wrap that
+ * Pass 9 emits around a component's view when the component has any
+ * `provide X with Y` declarations.
+ *
+ * Plain readonly object instead of just `ReadonlyMap` so future fields
+ * (e.g. a debug label) can be added without a breaking shape change.
+ */
+export interface ServiceOverrideMap {
+    readonly map: ReadonlyMap<string, unknown>;
+}
+/**
+ * The empty map used as the default `ServiceContext` value (no overrides
+ * — every `useService(name)` falls through to `ServiceRegistry.get`).
+ * Exported so tests can compare against it and the codegen can short-
+ * circuit composing an empty additions object.
+ */
+export declare const EMPTY_OVERRIDES: ServiceOverrideMap;
+/**
+ * React context carrying the service-override map for the current subtree.
+ * Initial value is `EMPTY_OVERRIDES` so a component that doesn't sit under
+ * any `<ServiceContext.Provider>` still reads via the singleton-fallback
+ * path. The context is shared across the whole app — a SINGLE context,
+ * not one-per-service, so the runtime stays simple at the cost of a tiny
+ * per-render lookup hit (a single `Map.get`).
+ */
+export declare const ServiceContext: import("react").Context<ServiceOverrideMap>;
+/**
+ * Pure-logic resolver — used by tests AND by {@link useService}. Looks
+ * `name` up in `overrides`; on miss, falls through to `ServiceRegistry`'s
+ * singleton. Exported so the inject/provide tests can exercise the
+ * fallback chain without standing up a React renderer.
+ */
+export declare const resolveServiceFromOverrides: <T extends ServiceInstance = ServiceInstance>(name: string, overrides: ServiceOverrideMap) => T;
+/**
+ * Component-side service read. The compiler emits this in place of
+ * `ServiceRegistry.get` for `inject service X` in component bodies, so
+ * the call site honours any ancestor `provide X with Y` override.
+ *
+ * Reads the nearest enclosing `ServiceContext` via `React.use` (React 19),
+ * then delegates to {@link resolveServiceFromOverrides}. Service-to-service
+ * injections (inside a service body, not a component) continue to use
+ * `ServiceRegistry.get` directly — there's no React render context
+ * available there to read.
+ */
+export declare const useService: <T extends ServiceInstance = ServiceInstance>(name: string) => T;
+/**
+ * Pure helper — layer `additions` on top of `parent`'s map, with the
+ * additions WINNING (child `provide` overrides ancestor `provide` for the
+ * same name). The compiler wraps the call in `useMemo` so the provider
+ * value is stable across re-renders unless the parent map or additions
+ * change identity. Pass-9 emits one entry per `provide X with Y` in the
+ * component body — `additions = { X: ServiceRegistry.get("Y") }`.
+ *
+ * Returns a NEW map; never mutates the input. Passing an empty
+ * `additions` returns the parent's map identity (avoids spurious context
+ * value churn when a component declared `provide` for no service after
+ * all — e.g. after a refactor).
+ */
+export declare const composeOverrides: (parent: ServiceOverrideMap, additions: Readonly<Record<string, unknown>>) => ServiceOverrideMap;
+/**
+ * Minimal duck-type for `RouterRegistry` — the only method this helper
+ * cares about is `subscribe`. Avoids a compile-time dependency on
+ * `@reactra/router` (which would invert today's import graph).
+ */
+export interface RouterLike {
+    subscribe(onChange: () => void): () => void;
+    /**
+     * Present on the real `RouterRegistry` (Middleware spec v2 §3): the slot
+     * `bindScopedServicesToRouter` installs the middleware `ctx.service`
+     * resolver into. Optional so test doubles that only exercise the scoped
+     * lifecycle stay valid.
+     */
+    __setMiddlewareServiceResolver?(resolver: (name: string) => unknown): void;
+}
+/**
+ * Wire scoped services to the router's route-change lifecycle. On the
+ * first invocation, activates every registered scoped service (the app
+ * just landed on its initial route). On every subsequent route change,
+ * deactivates the previous route's instances + activates fresh ones for
+ * the new route.
+ *
+ * Returns an unsubscribe function — call it on app teardown (rarely
+ * needed in browser, useful in tests).
+ *
+ * KNOWN LIMITATION (Stage 3 of Service Strategy B): the router's
+ * `subscribe` listeners fire AFTER `setLocation`'s onEnter has already
+ * called the new route's stores. So a store's `onEnter` reading a scoped
+ * service still sees the PREVIOUS route's instance until the next
+ * microtask. Components (which read via useService → React.use →
+ * re-render) see the new instance on the very next render. Spec-faithful
+ * pre-onEnter scope activation needs a router-side hook the runtime
+ * doesn't expose yet — filed as a follow-up.
+ *
+ *   // main.tsx
+ *   import { RouterRegistry } from "@reactra/router"
+ *   import { bindScopedServicesToRouter } from "@reactra/service"
+ *   ...
+ *   configureRouter({ ... })
+ *   bindScopedServicesToRouter(RouterRegistry)
+ */
+export declare const bindScopedServicesToRouter: (router: RouterLike) => (() => void);
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA+BA;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,eAAe,CAAA;IAC9B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,cAAM,mBAAmB;IACvB,OAAO,CAAC,SAAS,CAAqC;IAMtD,OAAO,CAAC,eAAe,CAA2C;IAElE;;;;;;OAMG;IACH,QAAQ,GAAI,SAAS,cAAc,KAAG,IAAI,CAgBzC;IAED;;;;;;;OAOG;IACH,sBAAsB,QAAO,IAAI,CAKhC;IAED;;;;;;OAMG;IACH,wBAAwB,QAAO,IAAI,CAmBlC;IAED;;;;OAIG;IACH,GAAG,GAAI,CAAC,SAAS,eAAe,GAAG,eAAe,EAAE,MAAM,MAAM,KAAG,CAAC,CAQnE;IAED,8EAA8E;IAC9E,GAAG,GAAI,MAAM,MAAM,KAAG,OAAO,CAA4B;IAEzD;;;;;;;;;;;;;;OAcG;IACH,OAAO,GAAI,SAAS,cAAc,KAAG,IAAI,CAExC;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,qBAA4B,CAAA;AAExD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAA;CAAE,KAAG,IAExE,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,eAAe,KAAG,eAA0B,CAAA;AAM/F;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,kBAAuC,CAAA;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,6CAAqD,CAAA;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GAAI,CAAC,SAAS,eAAe,GAAG,eAAe,EACrF,MAAM,MAAM,EACZ,WAAW,kBAAkB,KAC5B,CAIF,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,eAAe,GAAG,eAAe,EACpE,MAAM,MAAM,KACX,CAA8D,CAAA;AAEjE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,kBAAkB,EAC1B,WAAW,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAC3C,kBAMF,CAAA;AAID;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,8BAA8B,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAA;CAC3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,UAAU,KAAG,CAAC,MAAM,IAAI,CAgB1E,CAAA"}

package/dist/index.js

@@ -0,0 +1,272 @@
+// @reactra/service — Strategy A singletons + Strategy B `provide` runtime
+//
+// Owner: reactra-service-spec.md (Spec 2.0 / Discussion v2)
+//
+// What's shipped:
+//   ServiceRegistry: register / get / has / replace (HMR)
+//   configureServices({ services })
+//   createServiceInstance — helper consumed by compiler-emitted factories
+//
+// Strategy B runtime (Wave 3 §2b — this commit):
+//   ServiceContext        — React context carrying the override map for the
+//                           current subtree.
+//   useService<T>(name)   — read a service from the nearest enclosing
+//                           override map; falls back to ServiceRegistry's
+//                           singleton when not overridden. The compiler
+//                           emits this in place of `ServiceRegistry.get`
+//                           for component-side `inject service X` once the
+//                           Pass-9 changes (next commit) land.
+//   composeOverrides      — pure helper Pass-9 wraps in `useMemo` to build
+//                           the value the component's <ServiceContext.Provider>
+//                           passes down. Layers `additions` on top of
+//                           `parent` so a child `provide` overrides the
+//                           ancestor for the same name.
+//
+// Still deferred to subsequent commits:
+//   Pass-1.1 `provide X with Y` preprocessor + AST + Pass 5c + Pass 9 emit
+//   `service scoped` route-co-located lifecycle (depends on router glue)
+//   `service server` server-action emission (React 19 "use server")
+//   AbortSignal auto-injection from resources (Service spec §8.4)
+//   Dead-code elimination of unused methods (Pass 6b)
+class ServiceRegistryImpl {
+    instances = new Map();
+    // Wave 3 §2b — scoped service factories registered but NOT instantiated
+    // at `configureServices` time. `activateScopedServices()` instantiates
+    // them on route enter; `deactivateScopedServices()` disposes them on
+    // exit. A separate map keeps the singleton/scoped registries clean —
+    // the `get` path still consults `instances` first either way.
+    scopedFactories = new Map();
+    /**
+     * Register a service binding. App-singleton (`scoped !== true`) is
+     * instantiated immediately so downstream services can resolve
+     * dependencies via `ServiceRegistry.get` during their own factory
+     * call. Scoped bindings (Wave 3 §2b) store the factory only — they
+     * spin up on `activateScopedServices()`.
+     */
+    register = (binding) => {
+        if (binding.scoped === true) {
+            if (this.scopedFactories.has(binding.name) || this.instances.has(binding.name)) {
+                throw new Error(`[reactra:service] SVC001: service "${binding.name}" is already registered`);
+            }
+            this.scopedFactories.set(binding.name, binding.factory);
+            return;
+        }
+        if (this.instances.has(binding.name)) {
+            throw new Error(`[reactra:service] SVC001: service "${binding.name}" is already registered`);
+        }
+        this.instances.set(binding.name, binding.factory());
+    };
+    /**
+     * Wave 3 §2b — instantiate every scoped service. Idempotent: a
+     * second activation without intervening deactivate is a no-op for
+     * services that already have a live instance (the user might call
+     * this twice on a route re-entry). Called by the router-bound
+     * lifecycle hook in `bindScopedServicesToRouter`; safe to call
+     * manually in tests.
+     */
+    activateScopedServices = () => {
+        for (const [name, factory] of this.scopedFactories) {
+            if (this.instances.has(name))
+                continue;
+            this.instances.set(name, factory());
+        }
+    };
+    /**
+     * Wave 3 §2b — dispose + drop every scoped service instance. For
+     * each scoped instance with a `dispose()` method, invokes it before
+     * deletion. Errors thrown by `dispose` are caught + console.error'd
+     * so a single misbehaving service can't block the next route's
+     * activation. Singleton instances are unaffected.
+     */
+    deactivateScopedServices = () => {
+        for (const name of this.scopedFactories.keys()) {
+            const inst = this.instances.get(name);
+            if (!inst)
+                continue;
+            const disposer = inst.dispose;
+            if (typeof disposer === "function") {
+                try {
+                    ;
+                    disposer.call(inst);
+                }
+                catch (err) {
+                    if (typeof console !== "undefined") {
+                        console.error(`[reactra:service] scoped service "${name}".dispose threw — continuing teardown`, err);
+                    }
+                }
+            }
+            this.instances.delete(name);
+        }
+    };
+    /**
+     * Look up a singleton by name. Throws if the service wasn't registered —
+     * usually means the user forgot to add it to `configureServices`, or
+     * listed it after a consumer in the same array.
+     */
+    get = (name) => {
+        const inst = this.instances.get(name);
+        if (!inst) {
+            throw new Error(`[reactra:service] service "${name}" was used before configureServices() registered it`);
+        }
+        return inst;
+    };
+    /** True if a service is registered. Used by tests + future provide wiring. */
+    has = (name) => this.instances.has(name);
+    /**
+     * HMR hot-replace a binding (Compiler §5.3). Compiler-emitted
+     * `import.meta.hot.accept(...)` blocks in service-bearing files call
+     * this after the module re-evaluates so the new factory takes effect
+     * without a full page reload.
+     *
+     * Services are stateless callable units (Service spec §1) so the
+     * replace is just an instance swap. Consumers that cached a reference
+     * via `inject X` at component-body top see the stale singleton until
+     * their own component re-renders (component-side Fast Refresh in the
+     * consumer file, or the next interaction). Phase-1 trade-off; matches
+     * the store-replace one-render-delay characteristic.
+     *
+     * Idempotent on an unknown name (treated as a fresh register).
+     */
+    replace = (binding) => {
+        this.instances.set(binding.name, binding.factory());
+    };
+}
+/**
+ * The process-wide service registry singleton. The compiler emits imports
+ * of this and `ServiceRegistry.get("X")` at every `inject X` site. User
+ * code typically doesn't touch it directly except through `configureServices`.
+ */
+export const ServiceRegistry = new ServiceRegistryImpl();
+/**
+ * Bootstrap call — invoked from `src/main.tsx` per Runtime v0 §5. Registers
+ * every service binding the app cares about. Order matters: a service must
+ * appear in this array after the services it injects, because each
+ * factory call resolves `inject` references eagerly via `ServiceRegistry.get`.
+ */
+export const configureServices = (opts) => {
+    for (const binding of opts.services)
+        ServiceRegistry.register(binding);
+};
+/**
+ * Compiler-emitted factories call this to build a `ServiceInstance`. The
+ * `build` callback returns the surface object — `{ methodName: fn, ... }`.
+ * This helper exists for symmetry with `createStoreInstance` and to leave a
+ * future hook for Strategy B context-wrapping; today it is a pass-through.
+ *
+ * Shape used by emitted code (see Pass 9 codegen):
+ *
+ *   createServiceInstance(() => {
+ *     const authService = ServiceRegistry.get("authService")
+ *     const get = async (id) => { ... authService.getToken() ... }
+ *     return { get }
+ *   })
+ */
+export const createServiceInstance = (build) => build();
+// ─── Strategy B — `provide` runtime ────────────────────────────────────────
+import { createContext, use } from "react";
+/**
+ * The empty map used as the default `ServiceContext` value (no overrides
+ * — every `useService(name)` falls through to `ServiceRegistry.get`).
+ * Exported so tests can compare against it and the codegen can short-
+ * circuit composing an empty additions object.
+ */
+export const EMPTY_OVERRIDES = { map: new Map() };
+/**
+ * React context carrying the service-override map for the current subtree.
+ * Initial value is `EMPTY_OVERRIDES` so a component that doesn't sit under
+ * any `<ServiceContext.Provider>` still reads via the singleton-fallback
+ * path. The context is shared across the whole app — a SINGLE context,
+ * not one-per-service, so the runtime stays simple at the cost of a tiny
+ * per-render lookup hit (a single `Map.get`).
+ */
+export const ServiceContext = createContext(EMPTY_OVERRIDES);
+/**
+ * Pure-logic resolver — used by tests AND by {@link useService}. Looks
+ * `name` up in `overrides`; on miss, falls through to `ServiceRegistry`'s
+ * singleton. Exported so the inject/provide tests can exercise the
+ * fallback chain without standing up a React renderer.
+ */
+export const resolveServiceFromOverrides = (name, overrides) => {
+    const override = overrides.map.get(name);
+    if (override !== undefined)
+        return override;
+    return ServiceRegistry.get(name);
+};
+/**
+ * Component-side service read. The compiler emits this in place of
+ * `ServiceRegistry.get` for `inject service X` in component bodies, so
+ * the call site honours any ancestor `provide X with Y` override.
+ *
+ * Reads the nearest enclosing `ServiceContext` via `React.use` (React 19),
+ * then delegates to {@link resolveServiceFromOverrides}. Service-to-service
+ * injections (inside a service body, not a component) continue to use
+ * `ServiceRegistry.get` directly — there's no React render context
+ * available there to read.
+ */
+export const useService = (name) => resolveServiceFromOverrides(name, use(ServiceContext));
+/**
+ * Pure helper — layer `additions` on top of `parent`'s map, with the
+ * additions WINNING (child `provide` overrides ancestor `provide` for the
+ * same name). The compiler wraps the call in `useMemo` so the provider
+ * value is stable across re-renders unless the parent map or additions
+ * change identity. Pass-9 emits one entry per `provide X with Y` in the
+ * component body — `additions = { X: ServiceRegistry.get("Y") }`.
+ *
+ * Returns a NEW map; never mutates the input. Passing an empty
+ * `additions` returns the parent's map identity (avoids spurious context
+ * value churn when a component declared `provide` for no service after
+ * all — e.g. after a refactor).
+ */
+export const composeOverrides = (parent, additions) => {
+    const keys = Object.keys(additions);
+    if (keys.length === 0)
+        return parent;
+    const merged = new Map(parent.map);
+    for (const k of keys)
+        merged.set(k, additions[k]);
+    return { map: merged };
+};
+/**
+ * Wire scoped services to the router's route-change lifecycle. On the
+ * first invocation, activates every registered scoped service (the app
+ * just landed on its initial route). On every subsequent route change,
+ * deactivates the previous route's instances + activates fresh ones for
+ * the new route.
+ *
+ * Returns an unsubscribe function — call it on app teardown (rarely
+ * needed in browser, useful in tests).
+ *
+ * KNOWN LIMITATION (Stage 3 of Service Strategy B): the router's
+ * `subscribe` listeners fire AFTER `setLocation`'s onEnter has already
+ * called the new route's stores. So a store's `onEnter` reading a scoped
+ * service still sees the PREVIOUS route's instance until the next
+ * microtask. Components (which read via useService → React.use →
+ * re-render) see the new instance on the very next render. Spec-faithful
+ * pre-onEnter scope activation needs a router-side hook the runtime
+ * doesn't expose yet — filed as a follow-up.
+ *
+ *   // main.tsx
+ *   import { RouterRegistry } from "@reactra/router"
+ *   import { bindScopedServicesToRouter } from "@reactra/service"
+ *   ...
+ *   configureRouter({ ... })
+ *   bindScopedServicesToRouter(RouterRegistry)
+ */
+export const bindScopedServicesToRouter = (router) => {
+    // Service-aware middleware (Middleware spec v2 §3): the same explicit
+    // bootstrap line also installs the `ctx.service` resolver — app singletons
+    // + currently-activated scoped instances, via the registry's own lookup
+    // (its SVC diagnostics propagate unchanged).
+    router.__setMiddlewareServiceResolver?.((name) => ServiceRegistry.get(name));
+    let activated = false;
+    return router.subscribe(() => {
+        if (!activated) {
+            ServiceRegistry.activateScopedServices();
+            activated = true;
+            return;
+        }
+        ServiceRegistry.deactivateScopedServices();
+        ServiceRegistry.activateScopedServices();
+    });
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@reactra/service",
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akhilshastri/reactra.git",
+    "directory": "packages/service"
+  },
+  "homepage": "https://reactra-docs.vercel.app",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "sideEffects": false,
+  "description": "Reactra service/DI runtime — dependency injection for Reactra apps."
+}