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

package/dist/esm/context/hooks.d.ts

@@ -0,0 +1,357 @@
+/**
+ * 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
+ */
+import type { ServiceToken } from './types';
+import type { SynapseContext } from './container';
+import type { ServiceRef, ServiceBinding } from './refs';
+/**
+ * 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);
+ * ```
+ */
+export declare function setGlobalContext(ctx: SynapseContext | undefined): void;
+/**
+ * Get the current global context.
+ *
+ * @throws {Error} If no context has been set.
+ * @since 1.2.0
+ */
+export declare function getContext(): SynapseContext;
+/**
+ * Try to get the global context; returns `undefined` if not set.
+ * @since 1.2.0
+ */
+export declare function tryGetContext(): SynapseContext | undefined;
+/**
+ * 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);
+ * ```
+ */
+export declare function useService<T>(token: ServiceToken<T>): T;
+/**
+ * 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
+ */
+export declare function tryUseService<T>(token: ServiceToken<T>): T | undefined;
+/**
+ * Base interface for framework-specific context adapters.
+ *
+ * Implement this interface to create adapters for React, Vue, Express,
+ * or any other framework. The adapter wraps a `SynapseContext` and
+ * provides framework-idiomatic access patterns.
+ *
+ * @typeParam TFrameworkOpts - Framework-specific options.
+ * @since 1.2.0
+ */
+export interface ContextAdapter<TFrameworkOpts = unknown> {
+    /** Adapter name (e.g. 'react', 'express', 'vue'). */
+    readonly name: string;
+    /** The underlying context. */
+    readonly context: SynapseContext;
+    /** Initialize the adapter with framework-specific options. */
+    init(opts?: TFrameworkOpts): void;
+    /** Tear down the adapter. */
+    destroy(): void | Promise<void>;
+}
+/**
+ * React adapter configuration.
+ * @since 1.2.0
+ */
+export interface ReactAdapterConfig {
+    /** If true, sets the global context on mount. @default true */
+    setGlobal?: boolean;
+}
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function createReactAdapter(ctx: SynapseContext): ContextAdapter<ReactAdapterConfig>;
+/**
+ * Server middleware adapter configuration.
+ * @since 1.2.0
+ */
+export interface ServerAdapterConfig {
+    /** Create a new scope per request. @default true */
+    scopePerRequest?: boolean;
+    /** Key on the request object to store the scoped context. @default 'synapseCtx' */
+    contextKey?: string;
+}
+/**
+ * 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 });
+ * });
+ * ```
+ */
+export declare function createServerMiddleware(ctx: SynapseContext, opts?: ServerAdapterConfig): (req: Record<string, unknown>, res: unknown, next: () => void) => void;
+/**
+ * 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();
+ * ```
+ */
+export declare function createServiceHook<T>(token: ServiceToken<T>): () => T;
+/**
+ * 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
+ */
+export declare function createBoundHook<T>(ctx: SynapseContext, token: ServiceToken<T>): () => T;
+/**
+ * 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);
+ * ```
+ */
+export declare function autoWire<T extends Record<string, ServiceToken>>(ctx: SynapseContext, tokens: T): {
+    [K in keyof T]: T[K] extends ServiceToken<infer U> ? U : never;
+};
+/**
+ * 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
+ * }, []);
+ * ```
+ */
+export declare function useSharedRef<T>(token: ServiceToken<T>): ServiceRef<T>;
+/**
+ * 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
+ * ```
+ */
+export declare function useBoundServices<T extends Record<string, ServiceToken>>(tokens: T): ServiceBinding<T>;
+/**
+ * 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
+ * ```
+ */
+export declare function withRef<T, R>(ctx: SynapseContext, token: ServiceToken<T>, fn: (service: T) => R): R;
+/**
+ * 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
+ * ```
+ */
+export declare function withRefAsync<T, R>(ctx: SynapseContext, token: ServiceToken<T>, fn: (service: T) => Promise<R>): Promise<R>;
+/**
+ * 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();
+ * ```
+ */
+export declare function createRefHook<T>(token: ServiceToken<T>): () => ServiceRef<T>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/esm/context/hooks.d.ts.map

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