@sylphx/lens-server 1.11.3 → 2.1.0

package/src/server/dataloader.ts

@@ -0,0 +1,60 @@
+/**
+ * @sylphx/lens-server - DataLoader
+ *
+ * Simple batching utility for N+1 prevention in field resolution.
+ * Batches multiple load calls within a single microtask.
+ */
+
+/**
+ * DataLoader batches multiple load calls within a single microtask.
+ * Used internally for efficient field resolution.
+ */
+export class DataLoader<K, V> {
+	private batch: Map<K, { resolve: (v: V | null) => void; reject: (e: Error) => void }[]> =
+		new Map();
+	private scheduled = false;
+
+	constructor(private batchFn: (keys: K[]) => Promise<(V | null)[]>) {}
+
+	async load(key: K): Promise<V | null> {
+		return new Promise((resolve, reject) => {
+			const existing = this.batch.get(key);
+			if (existing) {
+				existing.push({ resolve, reject });
+			} else {
+				this.batch.set(key, [{ resolve, reject }]);
+			}
+
+			if (!this.scheduled) {
+				this.scheduled = true;
+				queueMicrotask(() => this.flush());
+			}
+		});
+	}
+
+	private async flush(): Promise<void> {
+		this.scheduled = false;
+		const batch = this.batch;
+		this.batch = new Map();
+
+		const keys = Array.from(batch.keys());
+		if (keys.length === 0) return;
+
+		try {
+			const results = await this.batchFn(keys);
+			let i = 0;
+			for (const [_key, callbacks] of batch) {
+				const result = results[i++];
+				for (const { resolve } of callbacks) {
+					resolve(result);
+				}
+			}
+		} catch (error) {
+			for (const [, callbacks] of batch) {
+				for (const { reject } of callbacks) {
+					reject(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+		}
+	}
+}

package/src/server/selection.ts

@@ -0,0 +1,123 @@
+/**
+ * @sylphx/lens-server - Selection
+ *
+ * Field selection logic for query results.
+ */
+
+import type { NestedSelection, SelectionObject } from "./types.js";
+
+/**
+ * Check if a value is a NestedSelection with input.
+ */
+function isNestedSelection(value: unknown): value is NestedSelection {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		("input" in value || "select" in value) &&
+		!Array.isArray(value)
+	);
+}
+
+/**
+ * Extract the select object from a selection value.
+ * Handles: true, SelectionObject, { select: ... }, { input: ..., select: ... }
+ */
+function extractSelect(value: unknown): SelectionObject | null {
+	if (value === true) return null;
+	if (typeof value !== "object" || value === null) return null;
+
+	const obj = value as Record<string, unknown>;
+
+	// { input?: ..., select?: ... } pattern
+	if ("input" in obj || ("select" in obj && typeof obj.select === "object")) {
+		return (obj.select as SelectionObject) ?? null;
+	}
+
+	// { select: ... } pattern (without input)
+	if ("select" in obj && typeof obj.select === "object") {
+		return obj.select as SelectionObject;
+	}
+
+	// Direct SelectionObject
+	return value as SelectionObject;
+}
+
+/**
+ * Apply field selection to data.
+ * Recursively filters data to only include selected fields.
+ *
+ * Supports:
+ * - `field: true` - Include field as-is
+ * - `field: { select: {...} }` - Nested selection
+ * - `field: { input: {...}, select: {...} }` - Nested with input (input passed to resolvers)
+ *
+ * @param data - The data to filter
+ * @param select - Selection object specifying which fields to include
+ * @returns Filtered data with only selected fields
+ */
+export function applySelection(data: unknown, select: SelectionObject): unknown {
+	if (!data) return data;
+
+	if (Array.isArray(data)) {
+		return data.map((item) => applySelection(item, select));
+	}
+
+	if (typeof data !== "object") return data;
+
+	const obj = data as Record<string, unknown>;
+	const result: Record<string, unknown> = {};
+
+	// Always include id
+	if ("id" in obj) result.id = obj.id;
+
+	for (const [key, value] of Object.entries(select)) {
+		if (!(key in obj)) continue;
+
+		if (value === true) {
+			result[key] = obj[key];
+		} else if (typeof value === "object" && value !== null) {
+			const nestedSelect = extractSelect(value);
+			if (nestedSelect) {
+				result[key] = applySelection(obj[key], nestedSelect);
+			} else {
+				// No nested select means include the whole field
+				result[key] = obj[key];
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Extract nested inputs from a selection object.
+ * Returns a map of field paths to their input params.
+ * Used by resolvers to fetch nested data with the right params.
+ */
+export function extractNestedInputs(
+	select: SelectionObject,
+	prefix = "",
+): Map<string, Record<string, unknown>> {
+	const inputs = new Map<string, Record<string, unknown>>();
+
+	for (const [key, value] of Object.entries(select)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+
+		if (isNestedSelection(value) && value.input) {
+			inputs.set(path, value.input);
+		}
+
+		// Recurse into nested selections
+		if (typeof value === "object" && value !== null) {
+			const nestedSelect = extractSelect(value);
+			if (nestedSelect) {
+				const nestedInputs = extractNestedInputs(nestedSelect, path);
+				for (const [nestedPath, nestedInput] of nestedInputs) {
+					inputs.set(nestedPath, nestedInput);
+				}
+			}
+		}
+	}
+
+	return inputs;
+}

package/src/server/types.ts

@@ -0,0 +1,306 @@
+/**
+ * @sylphx/lens-server - Server Types
+ *
+ * Type definitions for Lens server configuration and operations.
+ */
+
+import type {
+	ContextValue,
+	EntityDef,
+	InferRouterContext,
+	MutationDef,
+	OptimisticDSL,
+	QueryDef,
+	Resolvers,
+	RouterDef,
+} from "@sylphx/lens-core";
+import type { PluginManager, ServerPlugin } from "../plugin/types.js";
+
+// =============================================================================
+// Selection Types
+// =============================================================================
+
+/**
+ * Nested selection object with optional input.
+ * Used for relations that need their own params.
+ */
+export interface NestedSelection {
+	/** Input/params for this nested query */
+	input?: Record<string, unknown>;
+	/** Field selection for this nested query */
+	select?: SelectionObject;
+}
+
+/**
+ * Selection object for field selection.
+ * Supports:
+ * - `true` - Select this field
+ * - `{ select: {...} }` - Nested selection only
+ * - `{ input: {...}, select?: {...} }` - Nested with input params
+ */
+export interface SelectionObject {
+	[key: string]: boolean | SelectionObject | { select: SelectionObject } | NestedSelection;
+}
+
+// =============================================================================
+// Map Types
+// =============================================================================
+
+/** Entity map type */
+export type EntitiesMap = Record<string, EntityDef<string, any>>;
+
+/** Queries map type */
+export type QueriesMap = Record<string, QueryDef<unknown, unknown>>;
+
+/** Mutations map type */
+export type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
+
+// =============================================================================
+// Operation Metadata
+// =============================================================================
+
+/** Operation metadata for handshake */
+export interface OperationMeta {
+	type: "query" | "mutation" | "subscription";
+	optimistic?: OptimisticDSL;
+}
+
+/** Nested operations structure for handshake */
+export type OperationsMap = {
+	[key: string]: OperationMeta | OperationsMap;
+};
+
+// =============================================================================
+// Logger
+// =============================================================================
+
+/** Logger interface */
+export interface LensLogger {
+	info?: (message: string, ...args: unknown[]) => void;
+	warn?: (message: string, ...args: unknown[]) => void;
+	error?: (message: string, ...args: unknown[]) => void;
+}
+
+// =============================================================================
+// Server Configuration
+// =============================================================================
+
+/** Server configuration */
+export interface LensServerConfig<
+	TContext extends ContextValue = ContextValue,
+	TRouter extends RouterDef = RouterDef,
+> {
+	/** Entity definitions */
+	entities?: EntitiesMap | undefined;
+	/** Router definition (namespaced operations) */
+	router?: TRouter | undefined;
+	/** Query definitions (flat) */
+	queries?: QueriesMap | undefined;
+	/** Mutation definitions (flat) */
+	mutations?: MutationsMap | undefined;
+	/** Field resolvers array */
+	resolvers?: Resolvers | undefined;
+	/** Logger for server messages (default: silent) */
+	logger?: LensLogger | undefined;
+	/** Context factory */
+	context?: ((req?: unknown) => TContext | Promise<TContext>) | undefined;
+	/** Server version */
+	version?: string | undefined;
+	/**
+	 * Server-level plugins for subscription lifecycle and state management.
+	 * Plugins are processed at the server level, not adapter level.
+	 */
+	plugins?: ServerPlugin[] | undefined;
+}
+
+// =============================================================================
+// Server Metadata
+// =============================================================================
+
+/** Server metadata for transport handshake */
+export interface ServerMetadata {
+	version: string;
+	operations: OperationsMap;
+}
+
+// =============================================================================
+// Operations
+// =============================================================================
+
+/** Operation for execution */
+export interface LensOperation {
+	path: string;
+	input?: unknown;
+}
+
+/** Result from operation execution */
+export interface LensResult<T = unknown> {
+	data?: T;
+	error?: Error;
+}
+
+// =============================================================================
+// Client Communication
+// =============================================================================
+
+/**
+ * Client send function type for subscription updates.
+ */
+export type ClientSendFn = (message: unknown) => void;
+
+/** WebSocket interface for adapters */
+export interface WebSocketLike {
+	send(data: string): void;
+	close(): void;
+	onmessage?: ((event: { data: string }) => void) | null;
+	onclose?: (() => void) | null;
+	onerror?: ((error: unknown) => void) | null;
+}
+
+// =============================================================================
+// Server Interface
+// =============================================================================
+
+/**
+ * Lens server interface
+ *
+ * Core methods:
+ * - getMetadata() - Server metadata for transport handshake
+ * - execute() - Execute any operation
+ *
+ * Subscription support (used by adapters):
+ * - addClient() / removeClient() - Client connection management
+ * - subscribe() / unsubscribe() - Subscription lifecycle
+ * - send() - Send data to client (runs through plugin hooks)
+ * - broadcast() - Broadcast to all entity subscribers
+ * - handleReconnect() - Handle client reconnection
+ *
+ * The server handles all business logic including state management (via plugins).
+ * Handlers are pure protocol translators that call these methods.
+ */
+export interface LensServer {
+	/** Get server metadata for transport handshake */
+	getMetadata(): ServerMetadata;
+	/** Execute operation - auto-detects query vs mutation */
+	execute(op: LensOperation): Promise<LensResult>;
+
+	// =========================================================================
+	// Subscription Support (Optional - used by WS/SSE handlers)
+	// =========================================================================
+
+	/**
+	 * Register a client connection.
+	 * Call when a client connects via WebSocket/SSE.
+	 */
+	addClient(clientId: string, send: ClientSendFn): Promise<boolean>;
+
+	/**
+	 * Remove a client connection.
+	 * Call when a client disconnects.
+	 */
+	removeClient(clientId: string, subscriptionCount: number): void;
+
+	/**
+	 * Subscribe a client to an entity.
+	 * Runs plugin hooks and sets up state tracking (if clientState is enabled).
+	 */
+	subscribe(ctx: import("../plugin/types.js").SubscribeContext): Promise<boolean>;
+
+	/**
+	 * Unsubscribe a client from an entity.
+	 * Runs plugin hooks and cleans up state tracking.
+	 */
+	unsubscribe(ctx: import("../plugin/types.js").UnsubscribeContext): void;
+
+	/**
+	 * Send data to a client for a specific subscription.
+	 * Runs through plugin hooks (beforeSend/afterSend) for optimization.
+	 */
+	send(
+		clientId: string,
+		subscriptionId: string,
+		entity: string,
+		entityId: string,
+		data: Record<string, unknown>,
+		isInitial: boolean,
+	): Promise<void>;
+
+	/**
+	 * Broadcast data to all subscribers of an entity.
+	 * Runs through plugin hooks for each subscriber.
+	 */
+	broadcast(entity: string, entityId: string, data: Record<string, unknown>): Promise<void>;
+
+	/**
+	 * Handle a reconnection request from a client.
+	 * Uses plugin hooks (onReconnect) for reconnection logic.
+	 */
+	handleReconnect(
+		ctx: import("../plugin/types.js").ReconnectContext,
+	): Promise<import("../plugin/types.js").ReconnectHookResult[] | null>;
+
+	/**
+	 * Update subscribed fields for a client's subscription.
+	 * Runs plugin hooks (onUpdateFields) to sync state.
+	 */
+	updateFields(ctx: import("../plugin/types.js").UpdateFieldsContext): Promise<void>;
+
+	/**
+	 * Get the plugin manager for direct hook access.
+	 */
+	getPluginManager(): PluginManager;
+}
+
+// =============================================================================
+// Type Inference
+// =============================================================================
+
+import type { FieldType } from "@sylphx/lens-core";
+
+export type InferInput<T> =
+	T extends QueryDef<infer I, any> ? I : T extends MutationDef<infer I, any> ? I : never;
+
+export type InferOutput<T> =
+	T extends QueryDef<any, infer O>
+		? O
+		: T extends MutationDef<any, infer O>
+			? O
+			: T extends FieldType<infer F>
+				? F
+				: never;
+
+export type InferApi<T> = T extends { _types: infer Types } ? Types : never;
+
+export type ServerConfigWithInferredContext<
+	TRouter extends RouterDef,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap,
+> = {
+	router: TRouter;
+	entities?: EntitiesMap;
+	queries?: Q;
+	mutations?: M;
+	resolvers?: Resolvers;
+	logger?: LensLogger;
+	context?: () => InferRouterContext<TRouter> | Promise<InferRouterContext<TRouter>>;
+	version?: string;
+	/** Server-level plugins (clientState, etc.) */
+	plugins?: ServerPlugin[];
+};
+
+export type ServerConfigLegacy<
+	TContext extends ContextValue,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap,
+> = {
+	router?: RouterDef | undefined;
+	entities?: EntitiesMap;
+	queries?: Q;
+	mutations?: M;
+	resolvers?: Resolvers;
+	logger?: LensLogger;
+	context?: () => TContext | Promise<TContext>;
+	version?: string;
+	/** Server-level plugins (clientState, etc.) */
+	plugins?: ServerPlugin[];
+};