typeferry 0.6.0

package/dist/server/client-node.js

@@ -0,0 +1,159 @@
+import { RateLimiter } from 'limiter';
+import { MessageType, Presentation, ServerEvents } from '../utils/index.js';
+import EventEmitter2 from '../utils/event-emitter.js';
+import { SocketState } from './types.js';
+export class ClientNode extends EventEmitter2 {
+    uuid;
+    isAuthenticated = false;
+    meta = {};
+    context = {};
+    userId = null;
+    user = null;
+    socket;
+    /** Framework-agnostic request exposed by the Hono adapter. */
+    req;
+    /** Framework-agnostic response exposed by the Hono adapter. */
+    res;
+    isServer = false;
+    limiter;
+    server;
+    headers = {};
+    remoteAddress;
+    userAgent;
+    constructor(server, socket, req, res, limit) {
+        super();
+        this.server = server;
+        this.socket = socket;
+        this.req = req;
+        this.res = res;
+        if (limit) {
+            this.limiter = new RateLimiter(limit === true
+                ? {
+                    tokensPerInterval: 60,
+                    interval: 60 * 1000,
+                }
+                : {
+                    tokensPerInterval: limit.max,
+                    interval: limit.interval,
+                });
+        }
+    }
+    get authenticated() {
+        return this.isAuthenticated;
+    }
+    set authenticated(authenticated) {
+        this.isAuthenticated = authenticated;
+    }
+    get readyState() {
+        return this.socket?.readyState;
+    }
+    setId(uuid) {
+        this.uuid = uuid;
+    }
+    setContext(context) {
+        this.context = this.authenticated ? context : {};
+        this.setUserId();
+    }
+    /**
+     * Extracts tracking properties (headers, IP, user-agent) from a request.
+     * Accepts both Node `IncomingMessage` and the framework-agnostic `TypeFerryRequest`.
+     */
+    setTrackingProperties(source) {
+        this.headers = (source.headers ?? {});
+        this.userAgent = source.headers?.['user-agent'] ?? '';
+        this.remoteAddress =
+            source.headers?.['x-forwarded-for'] ??
+                source.socket?.remoteAddress ??
+                source.ip ??
+                '';
+    }
+    // The user ID is used for authorizing the user's channel.
+    setUserId() {
+        if (!this.authenticated)
+            return;
+        const userId = this.context?.user?._id;
+        if (!userId) {
+            throw new Error('The auth function must return a user object with a valid "_id" property');
+        }
+        this.userId = String(this.context.user._id);
+        this.user = this.context.user;
+        this.server?.indexClientByUserId(this);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // WebSocket Message Emitters
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Sends a push event to the client.
+     * Uses the wire protocol `{ t: "event", ... }` envelope.
+     */
+    emitTypeFerryEvent(event, channel, params) {
+        this.sendTypeFerryEvent(event, channel, params);
+    }
+    /**
+     * Sends a push event and returns the native transport pressure.
+     *
+     * Live data delivery uses this result to avoid hiding slow consumers behind
+     * the WebSocket runtime's own queue.
+     */
+    sendTypeFerryEvent(event, channel, params) {
+        if (!this.socket || this.socket.readyState !== SocketState.OPEN) {
+            return { accepted: false, bufferedBytes: this.bufferedBytes };
+        }
+        try {
+            this.socket.send(Presentation.encode({
+                t: MessageType.EVENT,
+                uuid: Presentation.uuid(),
+                event,
+                channel,
+                params,
+            }));
+        }
+        catch {
+            return { accepted: false, bufferedBytes: this.bufferedBytes };
+        }
+        return { accepted: true, bufferedBytes: this.bufferedBytes };
+    }
+    /** Whether the transport exposes native queued-byte pressure. */
+    get supportsBufferedBytes() {
+        return typeof this.socket?.bufferedAmount === 'number';
+    }
+    /** Returns native bytes queued by the WebSocket runtime without sending. */
+    get bufferedBytes() {
+        try {
+            return this.socket?.bufferedAmount ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Sends an error to the client.
+     */
+    emitError(payload) {
+        if (!this.socket || this.socket.readyState !== SocketState.OPEN)
+            return;
+        this.socket.send(Presentation.encode(payload));
+    }
+    /**
+     * Sends authentication result to the client.
+     * Uses the wire protocol `{ t: "auth", ... }` envelope.
+     */
+    emitAuthResult(authenticated) {
+        if (!this.socket || this.socket.readyState !== SocketState.OPEN)
+            return;
+        this.socket.send(Presentation.encode({ t: MessageType.AUTH, authenticated }));
+    }
+    /** Idempotency guard — prevents duplicate DISCONNECT events. */
+    closed = false;
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.socket) {
+            this.socket.close();
+        }
+        this.emit(ServerEvents.DISCONNECT);
+        this.server.emit(ServerEvents.DISCONNECTION, this);
+    }
+}
+//# sourceMappingURL=client-node.js.map

package/dist/server/client-node.js.map

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

package/dist/server/create-method-proxy.d.ts

@@ -0,0 +1,2 @@
+import type { Server } from './server.js';
+export declare function createMethodProxy(server: Server, path?: string): {};

package/dist/server/create-method-proxy.js

@@ -0,0 +1,16 @@
+export function createMethodProxy(server, path = '') {
+    return new Proxy({}, {
+        get(_, prop) {
+            const newPath = path ? `${path}.${prop}` : prop;
+            return createMethodProxy(server, newPath);
+        },
+        set(_, prop, value) {
+            const propertyPath = path
+                ? `${path}.${prop}`
+                : prop;
+            server.addMethod(propertyPath, value?.[0] ?? value, value?.[1]);
+            return true;
+        },
+    });
+}
+//# sourceMappingURL=create-method-proxy.js.map

package/dist/server/create-method-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-method-proxy.js","sourceRoot":"","sources":["../../src/server/create-method-proxy.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,IAAI,GAAG,EAAE;IACzD,OAAO,IAAI,KAAK,CACd,EAAE,EACF;QACE,GAAG,CAAC,CAAC,EAAE,IAAI;YACT,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAc,EAAE,CAAC,CAAC,CAAE,IAAe,CAAA;YACrE,OAAO,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC3C,CAAC;QACD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK;YAChB,MAAM,YAAY,GAAG,IAAI;gBACvB,CAAC,CAAC,GAAG,IAAI,IAAI,IAAc,EAAE;gBAC7B,CAAC,CAAE,IAAe,CAAA;YACpB,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YAC/D,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CACF,CAAA;AACH,CAAC"}

package/dist/server/decorators/cached.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @Cached class/method decorator — enables result caching.
+ * @NoCache method decorator — disables caching for a specific method.
+ *
+ * @module typeferry/server/decorators/cached
+ */
+/**
+ * Enables result caching at the class or method level.
+ *
+ * When applied to a class, all methods inherit the cache setting.
+ * When applied to a method, it overrides/complements class-level settings.
+ *
+ * @param maxAge - Cache TTL in milliseconds (default: 60000)
+ *
+ * @example
+ * ```ts
+ * @Namespace('analytics')
+ * @Cached(30_000)
+ * class AnalyticsMethods { ... }
+ * ```
+ */
+export declare function Cached(maxAge?: number): <T extends (abstract new (...args: unknown[]) => unknown) | ((...args: never[]) => unknown)>(target: T, context: ClassDecoratorContext | ClassMethodDecoratorContext) => T;
+/**
+ * Disables caching for a specific method when the class has @Cached().
+ *
+ * @example
+ * ```ts
+ * @Namespace('analytics')
+ * @Cached(30_000)
+ * class AnalyticsMethods {
+ *   @Method()
+ *   @NoCache()
+ *   async realtime(client: ClientNode, params) { ... }
+ * }
+ * ```
+ */
+export declare function NoCache(): <T extends (...args: never[]) => unknown>(target: T, context: ClassMethodDecoratorContext) => T;

package/dist/server/decorators/cached.js

@@ -0,0 +1,65 @@
+/**
+ * @Cached class/method decorator — enables result caching.
+ * @NoCache method decorator — disables caching for a specific method.
+ *
+ * @module typeferry/server/decorators/cached
+ */
+import { getOrCreateMethodMeta, getOrCreateNamespaceMeta, queueMethodUpdate, } from './metadata.js';
+const DEFAULT_MAX_AGE = 60_000;
+/**
+ * Enables result caching at the class or method level.
+ *
+ * When applied to a class, all methods inherit the cache setting.
+ * When applied to a method, it overrides/complements class-level settings.
+ *
+ * @param maxAge - Cache TTL in milliseconds (default: 60000)
+ *
+ * @example
+ * ```ts
+ * @Namespace('analytics')
+ * @Cached(30_000)
+ * class AnalyticsMethods { ... }
+ * ```
+ */
+export function Cached(maxAge) {
+    return function (target, context) {
+        if (context.kind === 'class') {
+            const meta = getOrCreateNamespaceMeta(target);
+            meta.cached = true;
+            meta.maxAge = maxAge ?? DEFAULT_MAX_AGE;
+            return target;
+        }
+        const key = String(context.name);
+        queueMethodUpdate(Class => {
+            const meta = getOrCreateMethodMeta(Class, key);
+            meta.cached = true;
+            meta.maxAge = maxAge ?? DEFAULT_MAX_AGE;
+        });
+        return target;
+    };
+}
+/**
+ * Disables caching for a specific method when the class has @Cached().
+ *
+ * @example
+ * ```ts
+ * @Namespace('analytics')
+ * @Cached(30_000)
+ * class AnalyticsMethods {
+ *   @Method()
+ *   @NoCache()
+ *   async realtime(client: ClientNode, params) { ... }
+ * }
+ * ```
+ */
+export function NoCache() {
+    return function (target, context) {
+        const key = String(context.name);
+        queueMethodUpdate(Class => {
+            const meta = getOrCreateMethodMeta(Class, key);
+            meta.cached = false;
+        });
+        return target;
+    };
+}
+//# sourceMappingURL=cached.js.map

package/dist/server/decorators/cached.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.js","sourceRoot":"","sources":["../../../src/server/decorators/cached.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAEnB,MAAM,eAAe,GAAG,MAAM,CAAA;AAE9B;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CAAC,MAAe;IACpC,OAAO,UAKL,MAAS,EACT,OAA4D;QAE5D,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,wBAAwB,CACnC,MAAsD,CACvD,CAAA;YACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;YAClB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,eAAe,CAAA;YACvC,OAAO,MAAM,CAAA;QACf,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAEhC,iBAAiB,CAAC,KAAK,CAAC,EAAE;YACxB,MAAM,IAAI,GAAG,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;YAClB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,eAAe,CAAA;QACzC,CAAC,CAAC,CAAA;QAEF,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO;IACrB,OAAO,UACL,MAAS,EACT,OAAoC;QAEpC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAEhC,iBAAiB,CAAC,KAAK,CAAC,EAAE;YACxB,MAAM,IAAI,GAAG,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YAC9C,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACrB,CAAC,CAAC,CAAA;QAEF,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;AACH,CAAC"}

package/dist/server/decorators/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * TypeFerry decorator API — class/decorator-based alternative to the ns() builder.
+ *
+ * @module typeferry/server/decorators
+ */
+export { Cached, NoCache } from './cached.js';
+export type { InferNamespace } from './infer.js';
+export type { MethodMeta, NamespaceMeta } from './metadata.js';
+export { Method } from './method.js';
+export { Namespace } from './namespace.js';
+export { Protected, Public } from './protected.js';
+export { registerNamespace } from './register.js';
+export { Schema } from './schema.js';
+export { Use } from './use.js';

package/dist/server/decorators/index.js

@@ -0,0 +1,13 @@
+/**
+ * TypeFerry decorator API — class/decorator-based alternative to the ns() builder.
+ *
+ * @module typeferry/server/decorators
+ */
+export { Cached, NoCache } from './cached.js';
+export { Method } from './method.js';
+export { Namespace } from './namespace.js';
+export { Protected, Public } from './protected.js';
+export { registerNamespace } from './register.js';
+export { Schema } from './schema.js';
+export { Use } from './use.js';
+//# sourceMappingURL=index.js.map

package/dist/server/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/decorators/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAG1C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA"}

package/dist/server/decorators/infer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Type-level utilities for extracting client-callable method types from
+ * decorator-based TypeFerry namespace classes.
+ *
+ * Bridges the gap between runtime decorator metadata and compile-time
+ * type inference, enabling autocomplete on `client.m.ai.generation.abort(...)`.
+ *
+ * @module typeferry/server/decorators/infer
+ */
+import type { ClientNode } from '../client-node.js';
+import type { CallOptions } from '../../utils/index.js';
+/**
+ * Extracts `{ params: P; result: R }` from a TypeFerry method signature.
+ *
+ * Uses tuple extraction on `Args` to distinguish 1-param from 2-param
+ * methods, avoiding function bivariance where `(a) => R` would incorrectly
+ * match `(a, b: infer P) => R`.
+ */
+type ExtractMethodSignature<T> = T extends (...args: infer Args) => Promise<infer R> ? Args extends [ClientNode, infer P] ? {
+    params: P;
+    result: R;
+} : Args extends [ClientNode] ? {
+    params: undefined;
+    result: R;
+} : never : never;
+/**
+ * Maps class methods to client-callable signatures.
+ * Filters out non-TypeFerry methods (those without `ClientNode` first param).
+ */
+type MethodsOf<T> = {
+    [K in keyof T as ExtractMethodSignature<T[K]> extends never ? never : K]: ExtractMethodSignature<T[K]> extends {
+        params: infer P;
+        result: infer R;
+    } ? P extends undefined ? (options?: CallOptions) => Promise<R> : (params: P, options?: CallOptions) => Promise<R> : never;
+};
+/**
+ * Converts a dotted path string into a nested object type.
+ *
+ * @example
+ * ```ts
+ * PathToNested<'ai.generation', { abort: fn }>
+ * // → { ai: { generation: { abort: fn } } }
+ * ```
+ */
+type PathToNested<Path extends string, Value> = Path extends `${infer Head}.${infer Rest}` ? {
+    [K in Head]: PathToNested<Rest, Value>;
+} : {
+    [K in Path]: Value;
+};
+/**
+ * Infers a client-side type map from a decorated TypeFerry namespace class.
+ *
+ * Extracts method signatures matching `(client: ClientNode, params: P) => Promise<R>`
+ * and wraps them in a nested object keyed by the dotted prefix.
+ *
+ * @example
+ * ```ts
+ * // Server class:
+ * \@Namespace('ai.generation')
+ * class AiGenerationMethods {
+ *   async abort(client: ClientNode, params: \{ generationId: string \}): Promise<void> \{ ... \}
+ * }
+ *
+ * // Companion type (one line per class):
+ * export type AiGenerationApi = InferNamespace<AiGenerationMethods, 'ai.generation'>
+ * // → \{ ai: \{ generation: \{ abort: (params: \{ generationId: string \}, options?) => Promise<void> \} \} \}
+ * ```
+ *
+ * Multiple namespaces compose via intersection:
+ * ```ts
+ * type AllAi = AiGenerationApi & AiMermaidApi & AiDeckApi
+ * ```
+ *
+ * @typeParam T - Class instance type (the decorated class)
+ * @typeParam Prefix - Dotted namespace prefix matching \@Namespace value
+ */
+export type InferNamespace<T, Prefix extends string> = Prefix extends '' ? MethodsOf<T> : PathToNested<Prefix, MethodsOf<T>>;
+export {};

package/dist/server/decorators/infer.js

@@ -0,0 +1,11 @@
+/**
+ * Type-level utilities for extracting client-callable method types from
+ * decorator-based TypeFerry namespace classes.
+ *
+ * Bridges the gap between runtime decorator metadata and compile-time
+ * type inference, enabling autocomplete on `client.m.ai.generation.abort(...)`.
+ *
+ * @module typeferry/server/decorators/infer
+ */
+export {};
+//# sourceMappingURL=infer.js.map

package/dist/server/decorators/infer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer.js","sourceRoot":"","sources":["../../../src/server/decorators/infer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/server/decorators/metadata.d.ts

@@ -0,0 +1,60 @@
+/**
+ * WeakMap-based metadata stores for TypeFerry decorator API.
+ *
+ * TC39 Stage 3 decorators don't have `reflect-metadata`, so we use WeakMaps
+ * keyed by class constructor (namespace) and class prototype (methods).
+ *
+ * Method decorators push updates to a pending queue instead of using
+ * `addInitializer` so metadata ownership stays explicit across classes defined
+ * in the same file. The @Namespace decorator flushes the queue after methods.
+ *
+ * @module typeferry/server/decorators/metadata
+ */
+import type { z } from 'zod';
+import type { AnyFunction } from '../../utils/index.js';
+/** Class-level metadata set by @Namespace, @Protected, @Cached */
+export interface NamespaceMeta {
+    prefix: string;
+    protected: boolean;
+    cached: boolean;
+    maxAge: number;
+}
+/** Per-method metadata set by @Method, @Schema, @Use, @Public, @Cached, @NoCache */
+export interface MethodMeta {
+    name: string;
+    schema?: z.ZodType;
+    middleware: AnyFunction[];
+    /** undefined = inherit from class */
+    protected?: boolean;
+    /** undefined = inherit from class */
+    cached?: boolean;
+    maxAge?: number;
+}
+/** Keyed by class constructor — stores namespace-level config */
+export declare const NAMESPACE_META: WeakMap<object, NamespaceMeta>;
+/** Keyed by class constructor — maps method property keys to their config */
+export declare const METHOD_META: WeakMap<object, Map<string, MethodMeta>>;
+/**
+ * Pending method metadata updates, flushed by @Namespace.
+ *
+ * Each entry is a function that receives the class constructor and applies
+ * its metadata. This avoids initializer ordering becoming shared state.
+ */
+export declare const PENDING_METHOD_UPDATES: Array<(Class: object) => void>;
+/** Get or initialize namespace metadata for a class constructor */
+export declare function getOrCreateNamespaceMeta(target: object): NamespaceMeta;
+/** Get or initialize the method metadata map for a class constructor */
+export declare function getOrCreateMethodMap(target: object): Map<string, MethodMeta>;
+/** Get or initialize metadata for a specific method on a class */
+export declare function getOrCreateMethodMeta(target: object, key: string): MethodMeta;
+/**
+ * Queue a method-level metadata update to be flushed by @Namespace.
+ *
+ * @param updater - Receives the class constructor when flushed
+ */
+export declare function queueMethodUpdate(updater: (Class: object) => void): void;
+/**
+ * Flush all pending method updates for the given class constructor.
+ * Called by @Namespace after all method decorators have run.
+ */
+export declare function flushPendingUpdates(Class: object): void;

package/dist/server/decorators/metadata.js

@@ -0,0 +1,77 @@
+/**
+ * WeakMap-based metadata stores for TypeFerry decorator API.
+ *
+ * TC39 Stage 3 decorators don't have `reflect-metadata`, so we use WeakMaps
+ * keyed by class constructor (namespace) and class prototype (methods).
+ *
+ * Method decorators push updates to a pending queue instead of using
+ * `addInitializer` so metadata ownership stays explicit across classes defined
+ * in the same file. The @Namespace decorator flushes the queue after methods.
+ *
+ * @module typeferry/server/decorators/metadata
+ */
+/** Keyed by class constructor — stores namespace-level config */
+export const NAMESPACE_META = new WeakMap();
+/** Keyed by class constructor — maps method property keys to their config */
+export const METHOD_META = new WeakMap();
+/**
+ * Pending method metadata updates, flushed by @Namespace.
+ *
+ * Each entry is a function that receives the class constructor and applies
+ * its metadata. This avoids initializer ordering becoming shared state.
+ */
+export const PENDING_METHOD_UPDATES = [];
+const DEFAULT_NAMESPACE_META = {
+    prefix: '',
+    protected: false,
+    cached: false,
+    maxAge: 60_000,
+};
+/** Get or initialize namespace metadata for a class constructor */
+export function getOrCreateNamespaceMeta(target) {
+    let meta = NAMESPACE_META.get(target);
+    if (!meta) {
+        meta = { ...DEFAULT_NAMESPACE_META };
+        NAMESPACE_META.set(target, meta);
+    }
+    return meta;
+}
+/** Get or initialize the method metadata map for a class constructor */
+export function getOrCreateMethodMap(target) {
+    let map = METHOD_META.get(target);
+    if (!map) {
+        map = new Map();
+        METHOD_META.set(target, map);
+    }
+    return map;
+}
+/** Get or initialize metadata for a specific method on a class */
+export function getOrCreateMethodMeta(target, key) {
+    const map = getOrCreateMethodMap(target);
+    let meta = map.get(key);
+    if (!meta) {
+        meta = { name: key, middleware: [] };
+        map.set(key, meta);
+    }
+    return meta;
+}
+/**
+ * Queue a method-level metadata update to be flushed by @Namespace.
+ *
+ * @param updater - Receives the class constructor when flushed
+ */
+export function queueMethodUpdate(updater) {
+    PENDING_METHOD_UPDATES.push(updater);
+}
+/**
+ * Flush all pending method updates for the given class constructor.
+ * Called by @Namespace after all method decorators have run.
+ */
+export function flushPendingUpdates(Class) {
+    while (PENDING_METHOD_UPDATES.length > 0) {
+        const updater = PENDING_METHOD_UPDATES.pop();
+        if (updater)
+            updater(Class);
+    }
+}
+//# sourceMappingURL=metadata.js.map

package/dist/server/decorators/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../../src/server/decorators/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,OAAO,EAAyB,CAAA;AAElE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,OAAO,EAAmC,CAAA;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAmC,EAAE,CAAA;AAExE,MAAM,sBAAsB,GAAkB;IAC5C,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,KAAK;IAChB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,MAAM;CACf,CAAA;AAED,mEAAmE;AACnE,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,IAAI,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,GAAG,EAAE,GAAG,sBAAsB,EAAE,CAAA;QACpC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,IAAI,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACjC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;QACf,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,GAAW;IAC/D,MAAM,GAAG,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAA;IACxC,IAAI,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACvB,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,CAAA;QACpC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACpB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgC;IAChE,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,sBAAsB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,EAAE,CAAA;QAC5C,IAAI,OAAO;YAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;AACH,CAAC"}

package/dist/server/decorators/method.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @Method decorator — marks a class method as a TypeFerry RPC endpoint.
+ *
+ * Queues a metadata update that @Namespace flushes after all method decorators
+ * have run. A pending queue keeps initializer ordering explicit across classes.
+ *
+ * @module typeferry/server/decorators/method
+ */
+/**
+ * Marks a class method as a TypeFerry RPC method.
+ *
+ * @param name - Optional override for the RPC method name (defaults to property key)
+ */
+export declare function Method(name?: string): <T extends (...args: never[]) => unknown>(target: T, context: ClassMethodDecoratorContext) => T;

package/dist/server/decorators/method.js

@@ -0,0 +1,25 @@
+/**
+ * @Method decorator — marks a class method as a TypeFerry RPC endpoint.
+ *
+ * Queues a metadata update that @Namespace flushes after all method decorators
+ * have run. A pending queue keeps initializer ordering explicit across classes.
+ *
+ * @module typeferry/server/decorators/method
+ */
+import { getOrCreateMethodMeta, queueMethodUpdate } from './metadata.js';
+/**
+ * Marks a class method as a TypeFerry RPC method.
+ *
+ * @param name - Optional override for the RPC method name (defaults to property key)
+ */
+export function Method(name) {
+    return function (target, context) {
+        const key = String(context.name);
+        queueMethodUpdate(Class => {
+            const meta = getOrCreateMethodMeta(Class, key);
+            meta.name = name ?? key;
+        });
+        return target;
+    };
+}
+//# sourceMappingURL=method.js.map

package/dist/server/decorators/method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method.js","sourceRoot":"","sources":["../../../src/server/decorators/method.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAErE;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAa;IAClC,OAAO,UACL,MAAS,EACT,OAAoC;QAEpC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAEhC,iBAAiB,CAAC,KAAK,CAAC,EAAE;YACxB,MAAM,IAAI,GAAG,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,GAAG,CAAA;QACzB,CAAC,CAAC,CAAA;QAEF,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;AACH,CAAC"}

package/dist/server/decorators/namespace.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @Namespace class decorator — registers a class as a TypeFerry RPC namespace.
+ *
+ * All methods in the class are prefixed with `{prefix}.{methodName}`.
+ * Also flushes pending @Method metadata into the class's WeakMap entry.
+ *
+ * @module typeferry/server/decorators/namespace
+ */
+type ClassConstructor = abstract new (...args: unknown[]) => unknown;
+/**
+ * Registers the decorated class as a TypeFerry namespace with the given prefix.
+ *
+ * Class decorators run after all method decorators, so we flush the pending
+ * update queue here — each queued updater receives this class constructor
+ * and writes its metadata into the class's WeakMap entry.
+ *
+ * @example
+ * ```ts
+ * @Namespace('boards')
+ * class BoardMethods { ... }
+ * // Methods register as: boards.get, boards.create, etc.
+ * ```
+ */
+export declare function Namespace(prefix: string): <T extends ClassConstructor>(target: T, _context: ClassDecoratorContext) => T;
+export {};