@spikard/node 0.9.0 → 0.10.1

package/config.d.ts

@@ -1,281 +0,0 @@
-/**
- * Configuration types for Spikard Node.js bindings
- *
- * These types mirror the Rust ServerConfig and related configuration structs.
- */
-
-/**
- * Compression configuration for response compression middleware.
- *
- * Spikard supports gzip and brotli compression for responses.
- * Compression is applied based on Accept-Encoding headers.
- */
-export interface CompressionConfig {
-	/** Enable gzip compression (default: true) */
-	gzip?: boolean;
-	/** Enable brotli compression (default: true) */
-	brotli?: boolean;
-	/** Minimum response size in bytes to compress (default: 1024) */
-	minSize?: number;
-	/** Compression quality level (0-11 for brotli, 0-9 for gzip, default: 6) */
-	quality?: number;
-}
-
-/**
- * Rate limiting configuration using Generic Cell Rate Algorithm (GCRA).
- *
- * By default, rate limits are applied per IP address.
- */
-export interface RateLimitConfig {
-	/** Maximum requests per second */
-	perSecond: number;
-	/** Burst allowance - allows temporary spikes */
-	burst: number;
-	/** Apply rate limits per IP address (default: true) */
-	ipBased?: boolean;
-}
-
-/**
- * JWT authentication configuration.
- *
- * Validates JWT tokens using the specified secret and algorithm.
- * Tokens are expected in the Authorization header as "Bearer <token>".
- *
- * Supported algorithms:
- * - HS256, HS384, HS512 (HMAC with SHA)
- * - RS256, RS384, RS512 (RSA signatures)
- * - ES256, ES384, ES512 (ECDSA signatures)
- * - PS256, PS384, PS512 (RSA-PSS signatures)
- */
-export interface JwtConfig {
-	/** Secret key for JWT validation */
-	secret: string;
-	/** JWT algorithm (default: "HS256") */
-	algorithm?: string;
-	/** Expected audience claim(s) */
-	audience?: string[];
-	/** Expected issuer claim */
-	issuer?: string;
-	/** Time leeway in seconds for exp/nbf/iat claims (default: 0) */
-	leeway?: number;
-}
-
-/**
- * API key authentication configuration.
- *
- * Validates API keys from request headers. Keys are matched exactly.
- */
-export interface ApiKeyConfig {
-	/** List of valid API keys */
-	keys: string[];
-	/** HTTP header name to check for API key (default: "X-API-Key") */
-	headerName?: string;
-}
-
-/**
- * Static file serving configuration.
- *
- * Serves files from a directory at a given route prefix.
- * Multiple static file configurations can be registered.
- */
-export interface StaticFilesConfig {
-	/** Directory path containing static files */
-	directory: string;
-	/** URL prefix for serving static files (e.g., "/static") */
-	routePrefix: string;
-	/** Serve index.html for directory requests (default: true) */
-	indexFile?: boolean;
-	/** Optional Cache-Control header value (e.g., "public, max-age=3600") */
-	cacheControl?: string;
-}
-
-/**
- * Contact information for OpenAPI documentation.
- */
-export interface ContactInfo {
-	/** Name of the contact person/organization */
-	name?: string;
-	/** Email address for contact */
-	email?: string;
-	/** URL for contact information */
-	url?: string;
-}
-
-/**
- * License information for OpenAPI documentation.
- */
-export interface LicenseInfo {
-	/** License name (e.g., "MIT", "Apache 2.0") */
-	name: string;
-	/** URL to the full license text */
-	url?: string;
-}
-
-/**
- * Server information for OpenAPI documentation.
- *
- * Multiple servers can be specified for different environments.
- */
-export interface ServerInfo {
-	/** Server URL (e.g., "https://api.example.com") */
-	url: string;
-	/** Description of the server (e.g., "Production", "Staging") */
-	description?: string;
-}
-
-/**
- * Security scheme configuration for OpenAPI documentation.
- *
- * Supports HTTP (Bearer/JWT) and API Key authentication schemes.
- */
-export type SecuritySchemeInfo =
-	| {
-			/** Security scheme type */
-			type: "http";
-			/** HTTP scheme (e.g., "bearer", "basic") */
-			scheme: string;
-			/** Format hint for Bearer tokens (e.g., "JWT") */
-			bearerFormat?: string;
-	  }
-	| {
-			/** Security scheme type */
-			type: "apiKey";
-			/** Where to look for the API key: "header", "query", or "cookie" */
-			location: "header" | "query" | "cookie";
-			/** Parameter name (e.g., "X-API-Key") */
-			name: string;
-	  };
-
-/**
- * OpenAPI 3.1.0 documentation configuration.
- *
- * Spikard can automatically generate OpenAPI documentation from your routes.
- * When enabled, it serves:
- * - Swagger UI at /docs (customizable)
- * - Redoc at /redoc (customizable)
- * - OpenAPI JSON spec at /openapi.json (customizable)
- *
- * Security schemes are auto-detected from middleware configuration.
- * Schemas are generated from your route type hints and validation.
- *
- * @example
- * ```typescript
- * const openapi: OpenApiConfig = {
- *   enabled: true,
- *   title: "My API",
- *   version: "1.0.0",
- *   description: "A great API built with Spikard",
- *   contact: {
- *     name: "API Team",
- *     email: "api@example.com",
- *     url: "https://example.com"
- *   },
- *   license: {
- *     name: "MIT",
- *     url: "https://opensource.org/licenses/MIT"
- *   },
- *   servers: [
- *     { url: "https://api.example.com", description: "Production" },
- *     { url: "http://localhost:8000", description: "Development" }
- *   ]
- * };
- * ```
- */
-export interface OpenApiConfig {
-	/** Enable OpenAPI generation (default: false for zero overhead) */
-	enabled?: boolean;
-	/** API title (required if enabled) */
-	title?: string;
-	/** API version (required if enabled) */
-	version?: string;
-	/** API description (supports Markdown) */
-	description?: string;
-	/** Path to serve Swagger UI (default: "/docs") */
-	swaggerUiPath?: string;
-	/** Path to serve Redoc (default: "/redoc") */
-	redocPath?: string;
-	/** Path to serve OpenAPI JSON spec (default: "/openapi.json") */
-	openapiJsonPath?: string;
-	/** Contact information for the API */
-	contact?: ContactInfo;
-	/** License information for the API */
-	license?: LicenseInfo;
-	/** List of server URLs for different environments */
-	servers?: ServerInfo[];
-	/** Custom security schemes (auto-detected if not provided) */
-	securitySchemes?: Record<string, SecuritySchemeInfo>;
-}
-
-/**
- * Complete server configuration for Spikard.
- *
- * This is the main configuration object that controls all aspects of the server
- * including network settings, middleware, authentication, and more.
- *
- * @example
- * ```typescript
- * import { Spikard } from 'spikard';
- *
- * const config: ServerConfig = {
- *   host: "0.0.0.0",
- *   port: 8080,
- *   workers: 4,
- *   compression: {
- *     quality: 9
- *   },
- *   rateLimit: {
- *     perSecond: 100,
- *     burst: 200
- *   },
- *   staticFiles: [
- *     {
- *       directory: "./public",
- *       routePrefix: "/static"
- *     }
- *   ],
- *   openapi: {
- *     enabled: true,
- *     title: "My API",
- *     version: "1.0.0"
- *   }
- * };
- *
- * const app = new Spikard(config);
- * ```
- */
-export interface ServerConfig {
-	/** Host address to bind to (default: "127.0.0.1") */
-	host?: string;
-	/** Port number to listen on (default: 8000, range: 1-65535) */
-	port?: number;
-	/** Number of worker processes (default: 1) */
-	workers?: number;
-
-	/** Add X-Request-ID header to responses (default: true) */
-	enableRequestId?: boolean;
-	/** Enable per-request HTTP tracing via tower-http TraceLayer (default: false) */
-	enableHttpTrace?: boolean;
-	/** Maximum request body size in bytes (default: 10MB, 0 or null for unlimited) */
-	maxBodySize?: number | null;
-	/** Request timeout in seconds (default: 30, null for no timeout) */
-	requestTimeout?: number | null;
-
-	/** Response compression configuration (default: enabled with defaults) */
-	compression?: CompressionConfig | null;
-	/** Rate limiting configuration (default: null/disabled) */
-	rateLimit?: RateLimitConfig | null;
-	/** JWT authentication configuration (default: null/disabled) */
-	jwtAuth?: JwtConfig | null;
-	/** API key authentication configuration (default: null/disabled) */
-	apiKeyAuth?: ApiKeyConfig | null;
-	/** List of static file serving configurations (default: empty array) */
-	staticFiles?: StaticFilesConfig[];
-
-	/** Enable graceful shutdown (default: true) */
-	gracefulShutdown?: boolean;
-	/** Graceful shutdown timeout in seconds (default: 30) */
-	shutdownTimeout?: number;
-
-	/** OpenAPI configuration (default: null/disabled) */
-	openapi?: OpenApiConfig | null;
-}

package/graphql.d.ts

@@ -1,287 +0,0 @@
-/**
- * GraphQL Schema Configuration Bindings for Node.js
- *
- * High-performance TypeScript bindings for configuring GraphQL schemas
- * with support for introspection control, complexity limits, and depth limits.
- *
- * @module spikard/graphql
- */
-
-/**
- * GraphQL Schema Configuration
- *
- * Represents the final configuration for a GraphQL schema after builder setup.
- * This object is passed to the GraphQL execution engine to apply constraints
- * and settings to query execution.
- *
- * @interface SchemaConfig
- */
-export interface SchemaConfig {
-	/**
-	 * Whether to enable GraphQL introspection queries.
-	 * Introspection allows clients to query the schema structure.
-	 *
-	 * @default true
-	 */
-	introspectionEnabled?: boolean;
-
-	/**
-	 * Maximum complexity allowed for queries (0 = unlimited).
-	 * Queries exceeding this complexity will be rejected.
-	 *
-	 * Complexity is calculated based on the query structure and field costs.
-	 * Typical production values: 1000-5000
-	 *
-	 * @default undefined (unlimited)
-	 */
-	complexityLimit?: number;
-
-	/**
-	 * Maximum depth allowed for queries (0 = unlimited).
-	 * Queries exceeding this depth will be rejected.
-	 *
-	 * Depth is the maximum nesting level of selections.
-	 * Typical production values: 15-25
-	 *
-	 * @default undefined (unlimited)
-	 */
-	depthLimit?: number;
-}
-
-/**
- * GraphQL Schema Builder
- *
- * Provides a fluent interface for building GraphQL schema configurations.
- * The builder follows the same pattern as the Rust SchemaBuilder with
- * mutations applied directly to the builder instance.
- *
- * @class GraphQLSchemaBuilder
- * @example
- * const builder = new GraphQLSchemaBuilder();
- * builder.enableIntrospection(true);
- * builder.complexityLimit(5000);
- * builder.depthLimit(50);
- * const config = builder.finish();
- */
-export class GraphQLSchemaBuilder {
-	/**
-	 * Create a new GraphQL schema builder with default settings
-	 *
-	 * Default configuration:
-	 * - Introspection enabled
-	 * - No complexity limit
-	 * - No depth limit
-	 *
-	 * @constructor
-	 */
-	constructor();
-
-	/**
-	 * Enable or disable GraphQL introspection
-	 *
-	 * Introspection is enabled by default. Disabling it prevents clients
-	 * from querying the schema structure via introspection queries, which
-	 * can be useful for security through obscurity in production.
-	 *
-	 * @param enabled - Whether to enable introspection
-	 * @returns void (mutates this instance)
-	 *
-	 * @example
-	 * builder.enableIntrospection(false);  // Disable introspection
-	 */
-	enableIntrospection(enabled: boolean): void;
-
-	/**
-	 * Set the maximum complexity allowed for queries
-	 *
-	 * The complexity is calculated based on the query structure and field costs.
-	 * Queries exceeding this limit will be rejected with a validation error.
-	 * A value of 0 means unlimited.
-	 *
-	 * Typical values:
-	 * - Production: 1000-5000
-	 * - Development: 10000+
-	 * - Testing: varies based on test scenarios
-	 *
-	 * @param limit - The maximum complexity allowed (0 = unlimited)
-	 * @returns void (mutates this instance)
-	 *
-	 * @example
-	 * builder.complexityLimit(5000);  // Allow up to 5000 complexity
-	 */
-	complexityLimit(limit: number): void;
-
-	/**
-	 * Set the maximum depth allowed for queries
-	 *
-	 * The depth is the maximum nesting level of selections in a query.
-	 * Queries exceeding this limit will be rejected with a validation error.
-	 * A value of 0 means unlimited.
-	 *
-	 * Typical values:
-	 * - Production: 15-25
-	 * - Development: 50-100
-	 * - Testing: varies based on test scenarios
-	 *
-	 * @param limit - The maximum depth allowed (0 = unlimited)
-	 * @returns void (mutates this instance)
-	 *
-	 * @example
-	 * builder.depthLimit(50);  // Allow up to 50 nesting levels
-	 */
-	depthLimit(limit: number): void;
-
-	/**
-	 * Check if introspection is currently enabled
-	 *
-	 * @returns true if introspection is enabled, false otherwise
-	 */
-	isIntrospectionEnabled(): boolean;
-
-	/**
-	 * Get the current complexity limit if set
-	 *
-	 * @returns The complexity limit, or null if unlimited
-	 */
-	getComplexityLimit(): number | null;
-
-	/**
-	 * Get the current depth limit if set
-	 *
-	 * @returns The depth limit, or null if unlimited
-	 */
-	getDepthLimit(): number | null;
-
-	/**
-	 * Build and return the schema configuration
-	 *
-	 * This method finalizes the configuration and returns a SchemaConfig object
-	 * that can be serialized and passed to the GraphQL execution engine.
-	 *
-	 * @returns A SchemaConfig instance with the configured settings
-	 *
-	 * @example
-	 * const builder = new GraphQLSchemaBuilder();
-	 * builder.complexityLimit(5000);
-	 * const config = builder.finish();
-	 * // config is now {
-	 * //   introspectionEnabled: true,
-	 * //   complexityLimit: 5000,
-	 * //   depthLimit: undefined
-	 * // }
-	 */
-	finish(): SchemaConfig;
-
-	/**
-	 * Convert the schema configuration to a JSON object
-	 *
-	 * This method serializes the current builder state to a JSON Value
-	 * for transmission to the Rust execution engine or storage.
-	 * Zero-copy serialization is used where possible.
-	 *
-	 * @returns A JSON representation of the schema configuration
-	 *
-	 * @example
-	 * const builder = new GraphQLSchemaBuilder();
-	 * builder.complexityLimit(5000);
-	 * const json = builder.to_json();
-	 * console.log(JSON.stringify(json, null, 2));
-	 */
-	to_json(): Record<string, any>;
-}
-
-/**
- * GraphQL Utilities and Factory Functions
- *
- * Provides factory methods for creating schema builders and configurations
- * with common patterns. All factory methods follow the same configuration
- * semantics as the SchemaBuilder.
- *
- * @class GraphQL
- *
- * @example
- * const builder = GraphQL.schemaBuilder();
- * const config = GraphQL.defaultSchemaConfig();
- * const queryConfig = GraphQL.queryOnlyConfig();
- */
-export class GraphQL {
-	/**
-	 * Create a new GraphQL schema builder
-	 *
-	 * Returns a builder instance that can be configured with various settings.
-	 * The builder uses fluent API with mutation methods (returns void).
-	 *
-	 * @static
-	 * @returns A new GraphQLSchemaBuilder instance with default settings
-	 *
-	 * @example
-	 * const builder = GraphQL.schemaBuilder()
-	 *   .enableIntrospection(true)
-	 *   .complexityLimit(5000)
-	 *   .depthLimit(50);
-	 */
-	static schemaBuilder(): GraphQLSchemaBuilder;
-
-	/**
-	 * Create a default schema configuration
-	 *
-	 * Returns a configuration with default settings:
-	 * - Introspection enabled
-	 * - No complexity limit
-	 * - No depth limit
-	 *
-	 * @static
-	 * @returns A SchemaConfig with default settings
-	 *
-	 * @example
-	 * const config = GraphQL.defaultSchemaConfig();
-	 * console.log(config.introspectionEnabled);  // true
-	 */
-	static defaultSchemaConfig(): SchemaConfig;
-
-	/**
-	 * Create a schema configuration for query-only schemas
-	 *
-	 * Returns a configuration suitable for schemas without mutations or
-	 * subscriptions. Useful for read-only APIs.
-	 *
-	 * @static
-	 * @returns A SchemaConfig optimized for query-only schemas
-	 *
-	 * @example
-	 * const config = GraphQL.queryOnlyConfig();
-	 * // Use this for read-only GraphQL endpoints
-	 */
-	static queryOnlyConfig(): SchemaConfig;
-
-	/**
-	 * Create a schema configuration for query and mutation schemas
-	 *
-	 * Returns a configuration suitable for schemas with queries and mutations
-	 * but no subscriptions. This is the most common pattern for REST-like
-	 * GraphQL APIs.
-	 *
-	 * @static
-	 * @returns A SchemaConfig optimized for query and mutation schemas
-	 *
-	 * @example
-	 * const config = GraphQL.queryMutationConfig();
-	 * // Use this for typical CRUD GraphQL endpoints
-	 */
-	static queryMutationConfig(): SchemaConfig;
-
-	/**
-	 * Create a full schema configuration
-	 *
-	 * Returns a configuration suitable for schemas with queries, mutations,
-	 * and subscriptions. Use this for real-time GraphQL APIs.
-	 *
-	 * @static
-	 * @returns A SchemaConfig optimized for full-featured schemas
-	 *
-	 * @example
-	 * const config = GraphQL.fullSchemaConfig();
-	 * // Use this for real-time GraphQL APIs with subscriptions
-	 */
-	static fullSchemaConfig(): SchemaConfig;
-}