@oobe-protocol-labs/synapse-client-sdk 1.0.7 → 1.2.0

package/dist/cjs/context/hooks.js

@@ -0,0 +1,451 @@
+"use strict";
+/**
+ * Framework-agnostic hooks and adapters for the Synapse context provider.
+ *
+ * Provides utilities to integrate the IoC container with any UI framework
+ * (React, Vue, Svelte, etc.) or backend framework (Express, Fastify,
+ * NestJS, etc.) via a simple adapter interface.
+ *
+ * ## Architecture
+ *
+ * ```
+ *  ┌──────────────────────────────────────────────────┐
+ *  │  ContextAdapter<Framework>                        │
+ *  │  ┌────────────────────┐  ┌─────────────────────┐ │
+ *  │  │ React: useService  │  │ Express: middleware  │ │
+ *  │  │ Vue:   inject      │  │ Fastify: decorator   │ │
+ *  │  └────────────────────┘  └─────────────────────┘ │
+ *  │           │                        │              │
+ *  │           ▼                        ▼              │
+ *  │  ┌──────────────────────────────────────────────┐ │
+ *  │  │           SynapseContext (IoC core)           │ │
+ *  │  └──────────────────────────────────────────────┘ │
+ *  └──────────────────────────────────────────────────┘
+ * ```
+ *
+ * @module context/hooks
+ * @since 1.2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setGlobalContext = setGlobalContext;
+exports.getContext = getContext;
+exports.tryGetContext = tryGetContext;
+exports.useService = useService;
+exports.tryUseService = tryUseService;
+exports.createReactAdapter = createReactAdapter;
+exports.createServerMiddleware = createServerMiddleware;
+exports.createServiceHook = createServiceHook;
+exports.createBoundHook = createBoundHook;
+exports.autoWire = autoWire;
+exports.useSharedRef = useSharedRef;
+exports.useBoundServices = useBoundServices;
+exports.withRef = withRef;
+exports.withRefAsync = withRefAsync;
+exports.createRefHook = createRefHook;
+// ── Global context holder ──────────────────────────────────────
+/**
+ * Module-level reference to the "current" context.
+ *
+ * Framework adapters can set this to make `getContext()` and
+ * `useService()` work without passing the context explicitly.
+ *
+ * @since 1.2.0
+ */
+let _globalContext;
+/**
+ * Set the global context reference.
+ *
+ * Call this once during application bootstrap. Framework adapters
+ * call this automatically.
+ *
+ * @param ctx - The context to make globally available.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * const ctx = createSynapseContext(config);
+ * setGlobalContext(ctx);
+ * ```
+ */
+function setGlobalContext(ctx) {
+    _globalContext = ctx;
+}
+/**
+ * Get the current global context.
+ *
+ * @throws {Error} If no context has been set.
+ * @since 1.2.0
+ */
+function getContext() {
+    if (!_globalContext) {
+        throw new Error('No Synapse context set. Call setGlobalContext(ctx) or use a framework adapter ' +
+            '(e.g. SynapseProvider for React) before calling getContext().');
+    }
+    return _globalContext;
+}
+/**
+ * Try to get the global context; returns `undefined` if not set.
+ * @since 1.2.0
+ */
+function tryGetContext() {
+    return _globalContext;
+}
+// ── Framework-agnostic service accessor ────────────────────────
+/**
+ * Resolve a service from the global context.
+ *
+ * This is the simplest way to access services without dependency on
+ * any specific framework. Works in Node.js, Deno, Bun, and browsers.
+ *
+ * @typeParam T - The service type.
+ * @param token - The service token to resolve.
+ * @returns The resolved service instance.
+ * @throws {Error} If no context is set.
+ * @throws {ServiceNotFoundError} If the token is not registered.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * import { useService, Tokens } from '@oobe-protocol-labs/synapse-client-sdk/context';
+ *
+ * const rpc = useService(Tokens.RPC);
+ * const balance = await rpc.getBalance(pubkey);
+ * ```
+ */
+function useService(token) {
+    return getContext().resolve(token);
+}
+/**
+ * Try to resolve a service from the global context.
+ * Returns `undefined` if no context is set or the token is not registered.
+ *
+ * @since 1.2.0
+ */
+function tryUseService(token) {
+    const ctx = tryGetContext();
+    if (!ctx)
+        return undefined;
+    return ctx.tryResolve(token);
+}
+/**
+ * Creates a React adapter blueprint.
+ *
+ * This does NOT depend on React — it returns plain functions and
+ * descriptors that a React wrapper can use. This keeps React as
+ * an optional peer dependency.
+ *
+ * @param ctx - The Synapse context to wrap.
+ * @returns Adapter blueprint with `Provider` props and hook factories.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * // In your React app:
+ * import React, { createContext, useContext } from 'react';
+ * import { createReactAdapter, Tokens } from '@oobe-protocol-labs/synapse-client-sdk/context';
+ *
+ * const adapter = createReactAdapter(ctx);
+ * const SynapseReactContext = createContext(adapter.context);
+ *
+ * function SynapseProvider({ children }) {
+ *   adapter.init({ setGlobal: true });
+ *   return <SynapseReactContext.Provider value={adapter.context}>{children}</SynapseReactContext.Provider>;
+ * }
+ *
+ * function useRpc() {
+ *   const ctx = useContext(SynapseReactContext);
+ *   return ctx.resolve(Tokens.RPC);
+ * }
+ * ```
+ */
+function createReactAdapter(ctx) {
+    return {
+        name: 'react',
+        context: ctx,
+        init(opts) {
+            if (opts?.setGlobal !== false) {
+                setGlobalContext(ctx);
+            }
+        },
+        destroy() {
+            if (_globalContext === ctx) {
+                setGlobalContext(undefined);
+            }
+        },
+    };
+}
+/**
+ * Create request-scoped middleware for Express/Fastify-style servers.
+ *
+ * Returns a middleware function that creates a child scope per
+ * request and attaches it to `req[contextKey]`.
+ *
+ * @param ctx  - The root Synapse context.
+ * @param opts - Server adapter options.
+ * @returns A middleware function `(req, res, next) => void`.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createSynapseContext, createServerMiddleware, Tokens } from '@oobe-protocol-labs/synapse-client-sdk/context';
+ *
+ * const ctx = createSynapseContext(config);
+ * const app = express();
+ *
+ * app.use(createServerMiddleware(ctx));
+ *
+ * app.get('/balance/:address', async (req, res) => {
+ *   const scope = req.synapseCtx;
+ *   const rpc = scope.resolve(Tokens.RPC);
+ *   const balance = await rpc.getBalance(Pubkey(req.params.address));
+ *   res.json({ balance });
+ * });
+ * ```
+ */
+function createServerMiddleware(ctx, opts = {}) {
+    const key = opts.contextKey ?? 'synapseCtx';
+    const scoped = opts.scopePerRequest !== false;
+    return (req, _res, next) => {
+        if (scoped) {
+            const requestId = req['id']
+                ?? `req-${Math.random().toString(36).slice(2, 9)}`;
+            const scope = ctx.createScope(requestId);
+            req[key] = scope;
+            // Auto-dispose the scope when the response finishes
+            const res = _res;
+            if (res && typeof res.on === 'function') {
+                res.on('finish', () => { scope.dispose().catch(() => { }); });
+            }
+        }
+        else {
+            req[key] = ctx;
+        }
+        next();
+    };
+}
+// ── Composable service "hooks" (framework-agnostic) ────────────
+/**
+ * Create a typed accessor function bound to a specific token.
+ *
+ * Returns a zero-argument function that resolves the service from
+ * the global context. Perfect for composable patterns.
+ *
+ * @param token - The service token.
+ * @returns A function `() => T` that resolves on each call.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * // Define once:
+ * const useRpc = createServiceHook(Tokens.RPC);
+ * const useDas = createServiceHook(Tokens.DAS);
+ *
+ * // Use anywhere:
+ * const rpc = useRpc();
+ * ```
+ */
+function createServiceHook(token) {
+    return () => useService(token);
+}
+/**
+ * Create a typed accessor bound to a specific context instance.
+ *
+ * Unlike `createServiceHook`, this does not use the global context —
+ * it's bound directly to the provided context.
+ *
+ * @param ctx   - The context to bind to.
+ * @param token - The service token.
+ * @returns A function `() => T`.
+ * @since 1.2.0
+ */
+function createBoundHook(ctx, token) {
+    return () => ctx.resolve(token);
+}
+// ── Utility: auto-wire ─────────────────────────────────────────
+/**
+ * Wire a plain object's methods to use services from the context.
+ *
+ * Creates a Proxy that resolves services lazily on property access.
+ * Useful for creating "service bags" that group multiple services.
+ *
+ * @param ctx    - The context to resolve from.
+ * @param tokens - A record of property names → service tokens.
+ * @returns A proxy object with lazy-resolved properties.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * const services = autoWire(ctx, {
+ *   rpc: Tokens.RPC,
+ *   das: Tokens.DAS,
+ *   programs: Tokens.PROGRAMS,
+ * });
+ *
+ * // Each property is resolved lazily:
+ * const balance = await services.rpc.getBalance(pubkey);
+ * const asset = await services.das.getAsset(assetId);
+ * ```
+ */
+function autoWire(ctx, tokens) {
+    const cache = new Map();
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop === 'symbol')
+                return undefined;
+            if (cache.has(prop))
+                return cache.get(prop);
+            const token = tokens[prop];
+            if (!token)
+                return undefined;
+            const instance = ctx.resolve(token);
+            cache.set(prop, instance);
+            return instance;
+        },
+        has(_target, prop) {
+            return typeof prop === 'string' && prop in tokens;
+        },
+        ownKeys() {
+            return Object.keys(tokens);
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (typeof prop === 'string' && prop in tokens) {
+                return { configurable: true, enumerable: true, writable: false };
+            }
+            return undefined;
+        },
+    });
+}
+// ── Memory-safe ref hooks ──────────────────────────────────────
+/**
+ * Acquire a tracked, ref-counted reference from the global context.
+ *
+ * The returned {@link ServiceRef} **must** be `.release()`'d when the
+ * component/module is done with the service. This ensures the SDK can
+ * track how many consumers hold a service and detect leaks.
+ *
+ * @typeParam T - The service type.
+ * @param token - The service token.
+ * @returns A new `ServiceRef<T>`.
+ * @throws {Error} If no global context is set.
+ * @throws {ServiceNotFoundError} If the token is not registered.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * // In a React component:
+ * useEffect(() => {
+ *   const rpcRef = useSharedRef(Tokens.RPC);
+ *   rpcRef.current.getBalance(pubkey).then(setBalance);
+ *   return () => rpcRef.release(); // cleanup on unmount
+ * }, []);
+ * ```
+ */
+function useSharedRef(token) {
+    return getContext().acquireRef(token);
+}
+/**
+ * Acquire tracked refs for multiple tokens from the global context.
+ *
+ * Returns a {@link ServiceBinding} whose `.services` proxy lazily
+ * resolves each token. A single `.release()` frees all refs at once.
+ *
+ * @param tokens - Record mapping property names to service tokens.
+ * @returns A binding with lazy services and batch release.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * const binding = useBoundServices({
+ *   rpc: Tokens.RPC,
+ *   das: Tokens.DAS,
+ * });
+ *
+ * await binding.services.rpc.getBalance(pubkey);
+ * binding.release(); // releases all
+ * ```
+ */
+function useBoundServices(tokens) {
+    return getContext().bind(tokens);
+}
+/**
+ * RAII pattern: acquire a ref, run `fn`, auto-release.
+ *
+ * The ref is released in a `finally` block so cleanup is guaranteed
+ * even if `fn` throws. Zero chance of leaking.
+ *
+ * @typeParam T - The service type.
+ * @typeParam R - The return type of `fn`.
+ * @param ctx   - The context to acquire from.
+ * @param token - The service token.
+ * @param fn    - Receives the unwrapped service value.
+ * @returns The return value of `fn`.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * const balance = withRef(ctx, Tokens.RPC, rpc => rpc.getBalance(pubkey));
+ * // ref is auto-released — no leak
+ * ```
+ */
+function withRef(ctx, token, fn) {
+    const ref = ctx.acquireRef(token);
+    try {
+        return fn(ref.current);
+    }
+    finally {
+        ref.release();
+    }
+}
+/**
+ * Async RAII pattern: acquire a ref, await `fn`, auto-release.
+ *
+ * @typeParam T - The service type.
+ * @typeParam R - The return type of `fn`.
+ * @param ctx   - The context to acquire from.
+ * @param token - The service token.
+ * @param fn    - Async function that receives the unwrapped service.
+ * @returns The return value of `fn`.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * const balance = await withRefAsync(ctx, Tokens.RPC, async rpc => {
+ *   return rpc.getBalance(pubkey);
+ * });
+ * // ref is auto-released after await
+ * ```
+ */
+async function withRefAsync(ctx, token, fn) {
+    const ref = ctx.acquireRef(token);
+    try {
+        return await fn(ref.current);
+    }
+    finally {
+        ref.release();
+    }
+}
+/**
+ * Create a reusable hook that acquires a tracked ref on each call.
+ *
+ * Unlike `createServiceHook` (which returns the raw service),
+ * this returns a `ServiceRef<T>` that must be released.
+ *
+ * @param token - The service token.
+ * @returns A function `() => ServiceRef<T>`.
+ * @since 1.2.0
+ *
+ * @example
+ * ```ts
+ * const useRpcRef = createRefHook(Tokens.RPC);
+ *
+ * // In a component:
+ * const rpcRef = useRpcRef();
+ * await rpcRef.current.getBalance(pubkey);
+ * rpcRef.release();
+ * ```
+ */
+function createRefHook(token) {
+    return () => useSharedRef(token);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/cjs/context/hooks.js.map

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

package/dist/cjs/context/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Synapse Context Provider — IoC service container with DI, scoping, and
+ * framework-agnostic hooks.
+ *
+ * Provides a type-safe dependency injection system for the Synapse SDK,
+ * enabling components, modules, and frameworks to access SDK services
+ * (RPC, DAS, WebSocket, Programs, AI Tools, etc.) through a unified
+ * context without tight coupling.
+ *
+ * ## Key exports
+ *
+ * | Export | Description |
+ * |--------|-------------|
+ * | {@link SynapseContext} | Core IoC container with register/resolve/scope |
+ * | {@link createSynapseContext} | Factory that wires all SDK services |
+ * | {@link Tokens} | Pre-defined tokens for every SDK module |
+ * | {@link useService} | Framework-agnostic service accessor |
+ * | {@link createServiceHook} | Composable typed accessor factory |
+ * | {@link autoWire} | Proxy-based lazy service bag |
+ * | {@link createReactAdapter} | React integration blueprint |
+ * | {@link createServerMiddleware} | Express/Fastify request-scoped DI |
+ *
+ * @module context
+ * @since 1.2.0
+ *
+ * @example Quick start
+ * ```ts
+ * import {
+ *   createSynapseContext,
+ *   Tokens,
+ *   useService,
+ *   setGlobalContext,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/context';
+ *
+ * // 1. Create context
+ * const ctx = createSynapseContext({
+ *   endpoint: 'https://rpc.synapse.com',
+ *   apiKey: 'sk-...',
+ * });
+ *
+ * // 2. Set as global (optional — enables useService())
+ * setGlobalContext(ctx);
+ *
+ * // 3. Resolve services anywhere
+ * const rpc = useService(Tokens.RPC);
+ * const programs = useService(Tokens.PROGRAMS);
+ *
+ * // 4. Create scoped contexts
+ * const scope = ctx.createScope('user-session');
+ * scope.register(USER_TOKEN, { useValue: currentUser });
+ *
+ * // 5. Cleanup
+ * await ctx.dispose();
+ * ```
+ *
+ * @example Custom module
+ * ```ts
+ * import { createSynapseContext, createToken, type ContextModule } from '...';
+ *
+ * interface Analytics { track(event: string): void; }
+ * const ANALYTICS = createToken<Analytics>('Analytics');
+ *
+ * const analyticsModule: ContextModule = {
+ *   name: 'analytics',
+ *   register(ctx) {
+ *     ctx.register(ANALYTICS, {
+ *       useFactory: () => new MixpanelAnalytics(),
+ *       lifecycle: 'singleton',
+ *     });
+ *   },
+ * };
+ *
+ * const ctx = createSynapseContext(config, { modules: [analyticsModule] });
+ * ```
+ */
+export { createToken, isDisposable, ServiceNotFoundError, CircularDependencyError, AsyncProviderError, type ServiceToken, type ServiceLifecycle, type ServiceProvider, type ValueProvider, type FactoryProvider, type ClassProvider, type AliasProvider, type AsyncFactoryProvider, type ServiceRegistration, type ServiceResolver, type ResolveMiddleware, type Disposable, type ContextEvents, } from './types';
+export { SynapseContext } from './container';
+export { ServiceRef, WeakServiceRef, RefRegistry, MemoryGuard, RefReleasedError, createBinding, type LeakReport, type RefStats, type RefRegistryConfig, type MemoryGuardConfig, type ServiceBinding, } from './refs';
+export { Tokens, createSynapseContext, createBareContext, type ProgramsBundle, type ContextModule, type CreateSynapseContextOpts, } from './providers';
+export { setGlobalContext, getContext, tryGetContext, useService, tryUseService, createServiceHook, createBoundHook, useSharedRef, useBoundServices, withRef, withRefAsync, createRefHook, createReactAdapter, createServerMiddleware, autoWire, type ContextAdapter, type ReactAdapterConfig, type ServerAdapterConfig, } from './hooks';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAGH,OAAO,EAEL,WAAW,EACX,YAAY,EAEZ,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAElB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EACL,MAAM,EACN,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,wBAAwB,GAC9B,MAAM,aAAa,CAAC;AAGrB,OAAO,EAEL,gBAAgB,EAChB,UAAU,EACV,aAAa,EAEb,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EAEf,YAAY,EACZ,gBAAgB,EAChB,OAAO,EACP,YAAY,EACZ,aAAa,EAEb,kBAAkB,EAClB,sBAAsB,EACtB,QAAQ,EAER,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,SAAS,CAAC"}

package/dist/cjs/context/index.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Synapse Context Provider — IoC service container with DI, scoping, and
+ * framework-agnostic hooks.
+ *
+ * Provides a type-safe dependency injection system for the Synapse SDK,
+ * enabling components, modules, and frameworks to access SDK services
+ * (RPC, DAS, WebSocket, Programs, AI Tools, etc.) through a unified
+ * context without tight coupling.
+ *
+ * ## Key exports
+ *
+ * | Export | Description |
+ * |--------|-------------|
+ * | {@link SynapseContext} | Core IoC container with register/resolve/scope |
+ * | {@link createSynapseContext} | Factory that wires all SDK services |
+ * | {@link Tokens} | Pre-defined tokens for every SDK module |
+ * | {@link useService} | Framework-agnostic service accessor |
+ * | {@link createServiceHook} | Composable typed accessor factory |
+ * | {@link autoWire} | Proxy-based lazy service bag |
+ * | {@link createReactAdapter} | React integration blueprint |
+ * | {@link createServerMiddleware} | Express/Fastify request-scoped DI |
+ *
+ * @module context
+ * @since 1.2.0
+ *
+ * @example Quick start
+ * ```ts
+ * import {
+ *   createSynapseContext,
+ *   Tokens,
+ *   useService,
+ *   setGlobalContext,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/context';
+ *
+ * // 1. Create context
+ * const ctx = createSynapseContext({
+ *   endpoint: 'https://rpc.synapse.com',
+ *   apiKey: 'sk-...',
+ * });
+ *
+ * // 2. Set as global (optional — enables useService())
+ * setGlobalContext(ctx);
+ *
+ * // 3. Resolve services anywhere
+ * const rpc = useService(Tokens.RPC);
+ * const programs = useService(Tokens.PROGRAMS);
+ *
+ * // 4. Create scoped contexts
+ * const scope = ctx.createScope('user-session');
+ * scope.register(USER_TOKEN, { useValue: currentUser });
+ *
+ * // 5. Cleanup
+ * await ctx.dispose();
+ * ```
+ *
+ * @example Custom module
+ * ```ts
+ * import { createSynapseContext, createToken, type ContextModule } from '...';
+ *
+ * interface Analytics { track(event: string): void; }
+ * const ANALYTICS = createToken<Analytics>('Analytics');
+ *
+ * const analyticsModule: ContextModule = {
+ *   name: 'analytics',
+ *   register(ctx) {
+ *     ctx.register(ANALYTICS, {
+ *       useFactory: () => new MixpanelAnalytics(),
+ *       lifecycle: 'singleton',
+ *     });
+ *   },
+ * };
+ *
+ * const ctx = createSynapseContext(config, { modules: [analyticsModule] });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoWire = exports.createServerMiddleware = exports.createReactAdapter = exports.createRefHook = exports.withRefAsync = exports.withRef = exports.useBoundServices = exports.useSharedRef = exports.createBoundHook = exports.createServiceHook = exports.tryUseService = exports.useService = exports.tryGetContext = exports.getContext = exports.setGlobalContext = exports.createBareContext = exports.createSynapseContext = exports.Tokens = exports.createBinding = exports.RefReleasedError = exports.MemoryGuard = exports.RefRegistry = exports.WeakServiceRef = exports.ServiceRef = exports.SynapseContext = exports.AsyncProviderError = exports.CircularDependencyError = exports.ServiceNotFoundError = exports.isDisposable = exports.createToken = void 0;
+// ── Types & tokens ─────────────────────────────────────────────
+var types_1 = require("./types");
+// Token creation
+Object.defineProperty(exports, "createToken", { enumerable: true, get: function () { return types_1.createToken; } });
+Object.defineProperty(exports, "isDisposable", { enumerable: true, get: function () { return types_1.isDisposable; } });
+// Error classes
+Object.defineProperty(exports, "ServiceNotFoundError", { enumerable: true, get: function () { return types_1.ServiceNotFoundError; } });
+Object.defineProperty(exports, "CircularDependencyError", { enumerable: true, get: function () { return types_1.CircularDependencyError; } });
+Object.defineProperty(exports, "AsyncProviderError", { enumerable: true, get: function () { return types_1.AsyncProviderError; } });
+// ── Container ──────────────────────────────────────────────────
+var container_1 = require("./container");
+Object.defineProperty(exports, "SynapseContext", { enumerable: true, get: function () { return container_1.SynapseContext; } });
+// ── Memory-safe references ─────────────────────────────────────
+var refs_1 = require("./refs");
+Object.defineProperty(exports, "ServiceRef", { enumerable: true, get: function () { return refs_1.ServiceRef; } });
+Object.defineProperty(exports, "WeakServiceRef", { enumerable: true, get: function () { return refs_1.WeakServiceRef; } });
+Object.defineProperty(exports, "RefRegistry", { enumerable: true, get: function () { return refs_1.RefRegistry; } });
+Object.defineProperty(exports, "MemoryGuard", { enumerable: true, get: function () { return refs_1.MemoryGuard; } });
+Object.defineProperty(exports, "RefReleasedError", { enumerable: true, get: function () { return refs_1.RefReleasedError; } });
+Object.defineProperty(exports, "createBinding", { enumerable: true, get: function () { return refs_1.createBinding; } });
+// ── Built-in providers & tokens ────────────────────────────────
+var providers_1 = require("./providers");
+Object.defineProperty(exports, "Tokens", { enumerable: true, get: function () { return providers_1.Tokens; } });
+Object.defineProperty(exports, "createSynapseContext", { enumerable: true, get: function () { return providers_1.createSynapseContext; } });
+Object.defineProperty(exports, "createBareContext", { enumerable: true, get: function () { return providers_1.createBareContext; } });
+// ── Hooks & adapters ───────────────────────────────────────────
+var hooks_1 = require("./hooks");
+// Global context
+Object.defineProperty(exports, "setGlobalContext", { enumerable: true, get: function () { return hooks_1.setGlobalContext; } });
+Object.defineProperty(exports, "getContext", { enumerable: true, get: function () { return hooks_1.getContext; } });
+Object.defineProperty(exports, "tryGetContext", { enumerable: true, get: function () { return hooks_1.tryGetContext; } });
+// Service accessors
+Object.defineProperty(exports, "useService", { enumerable: true, get: function () { return hooks_1.useService; } });
+Object.defineProperty(exports, "tryUseService", { enumerable: true, get: function () { return hooks_1.tryUseService; } });
+Object.defineProperty(exports, "createServiceHook", { enumerable: true, get: function () { return hooks_1.createServiceHook; } });
+Object.defineProperty(exports, "createBoundHook", { enumerable: true, get: function () { return hooks_1.createBoundHook; } });
+// Memory-safe ref hooks
+Object.defineProperty(exports, "useSharedRef", { enumerable: true, get: function () { return hooks_1.useSharedRef; } });
+Object.defineProperty(exports, "useBoundServices", { enumerable: true, get: function () { return hooks_1.useBoundServices; } });
+Object.defineProperty(exports, "withRef", { enumerable: true, get: function () { return hooks_1.withRef; } });
+Object.defineProperty(exports, "withRefAsync", { enumerable: true, get: function () { return hooks_1.withRefAsync; } });
+Object.defineProperty(exports, "createRefHook", { enumerable: true, get: function () { return hooks_1.createRefHook; } });
+// Framework adapters
+Object.defineProperty(exports, "createReactAdapter", { enumerable: true, get: function () { return hooks_1.createReactAdapter; } });
+Object.defineProperty(exports, "createServerMiddleware", { enumerable: true, get: function () { return hooks_1.createServerMiddleware; } });
+Object.defineProperty(exports, "autoWire", { enumerable: true, get: function () { return hooks_1.autoWire; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;;;AAEH,kEAAkE;AAClE,iCAsBiB;AArBf,iBAAiB;AACjB,oGAAA,WAAW,OAAA;AACX,qGAAA,YAAY,OAAA;AACZ,gBAAgB;AAChB,6GAAA,oBAAoB,OAAA;AACpB,gHAAA,uBAAuB,OAAA;AACvB,2GAAA,kBAAkB,OAAA;AAiBpB,kEAAkE;AAClE,yCAA6C;AAApC,2GAAA,cAAc,OAAA;AAEvB,kEAAkE;AAClE,+BAYgB;AAXd,kGAAA,UAAU,OAAA;AACV,sGAAA,cAAc,OAAA;AACd,mGAAA,WAAW,OAAA;AACX,mGAAA,WAAW,OAAA;AACX,wGAAA,gBAAgB,OAAA;AAChB,qGAAA,aAAa,OAAA;AAQf,kEAAkE;AAClE,yCAOqB;AANnB,mGAAA,MAAM,OAAA;AACN,iHAAA,oBAAoB,OAAA;AACpB,8GAAA,iBAAiB,OAAA;AAMnB,kEAAkE;AAClE,iCAwBiB;AAvBf,iBAAiB;AACjB,yGAAA,gBAAgB,OAAA;AAChB,mGAAA,UAAU,OAAA;AACV,sGAAA,aAAa,OAAA;AACb,oBAAoB;AACpB,mGAAA,UAAU,OAAA;AACV,sGAAA,aAAa,OAAA;AACb,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AACf,wBAAwB;AACxB,qGAAA,YAAY,OAAA;AACZ,yGAAA,gBAAgB,OAAA;AAChB,gGAAA,OAAO,OAAA;AACP,qGAAA,YAAY,OAAA;AACZ,sGAAA,aAAa,OAAA;AACb,qBAAqB;AACrB,2GAAA,kBAAkB,OAAA;AAClB,+GAAA,sBAAsB,OAAA;AACtB,iGAAA,QAAQ,OAAA"}