@buenojs/bueno 0.8.6 → 0.8.8

package/dist/graphql/types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * GraphQL Module Types
+ *
+ * Core type definitions for the Bueno GraphQL integration layer.
+ */
+export type Constructor<T = unknown> = new (...args: unknown[]) => T;
+/**
+ * Represents a GraphQL scalar type via its JS constructor.
+ * Usage: () => String, () => Number, () => Boolean, () => GraphQLID
+ */
+export type GraphQLScalar = StringConstructor | NumberConstructor | BooleanConstructor | typeof GraphQLID | typeof GraphQLInt | typeof GraphQLFloat;
+/**
+ * A thunk that returns a type constructor or array of constructors.
+ * Used to avoid circular reference issues in type definitions.
+ *
+ * @example
+ * () => String        // GraphQL String scalar
+ * () => Number        // GraphQL Float scalar
+ * () => [User]        // [User!]! list
+ * () => User          // User object type
+ */
+export type TypeFn = () => Constructor | Constructor[] | GraphQLScalar;
+/**
+ * Sentinel class representing GraphQL ID scalar.
+ * Usage: @Field(() => GraphQLID)
+ */
+export declare class GraphQLID {
+    static readonly __type = "ID";
+}
+/**
+ * Sentinel class representing GraphQL Int scalar.
+ * Usage: @Field(() => GraphQLInt)
+ */
+export declare class GraphQLInt {
+    static readonly __type = "Int";
+}
+/**
+ * Sentinel class representing GraphQL Float scalar.
+ * Usage: @Field(() => GraphQLFloat)
+ */
+export declare class GraphQLFloat {
+    static readonly __type = "Float";
+}
+/** Options for @Field decorator */
+export interface FieldDecoratorOptions {
+    /** Whether the field can be null (default: false → non-null) */
+    nullable?: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Deprecation reason */
+    deprecationReason?: string;
+    /** Default value for input types */
+    defaultValue?: unknown;
+}
+/** Options for @Query/@Mutation/@Subscription decorators */
+export interface FieldOptions extends FieldDecoratorOptions {
+    /** GraphQL field name override (default: method name) */
+    name?: string;
+}
+/** Metadata stored per @Field-decorated property */
+export interface FieldMetadata {
+    propertyKey: string;
+    typeFn: TypeFn;
+    nullable: boolean;
+    description?: string;
+    deprecationReason?: string;
+    defaultValue?: unknown;
+}
+/** Metadata for a single resolver method parameter */
+export interface ParamMetadata {
+    index: number;
+    kind: "args" | "argsObject" | "context";
+    /** For @Args('name') — the specific argument name */
+    argName?: string;
+    /** For @Args('name', InputType) — the input object type */
+    inputTypeFn?: TypeFn;
+}
+/** Metadata stored per @Query/@Mutation/@Subscription method */
+export interface ResolverFieldMetadata {
+    /** Actual method name on the class */
+    methodName: string;
+    /** GraphQL field name (defaults to methodName) */
+    fieldName: string;
+    typeFn: TypeFn;
+    kind: "query" | "mutation" | "subscription";
+    nullable: boolean;
+    description?: string;
+    deprecationReason?: string;
+    paramMetadata: ParamMetadata[];
+}
+/** Metadata stored per @Resolver-decorated class */
+export interface ResolverClassMetadata {
+    /** GraphQL type name (default: class name) */
+    name: string;
+}
+/** Metadata stored per @ObjectType / @InputType class */
+export interface TypeClassMetadata {
+    name: string;
+    kind: "object" | "input";
+    description?: string;
+}
+/** A single resolvable field in the built schema */
+export interface ResolvedField {
+    resolverInstance: unknown;
+    methodName: string;
+    paramMetadata: ParamMetadata[];
+    typeFn: TypeFn;
+    nullable: boolean;
+}
+/** Internal schema representation consumed by the built-in engine */
+export interface ResolvedSchema {
+    queryFields: Map<string, ResolvedField>;
+    mutationFields: Map<string, ResolvedField>;
+    subscriptionFields: Map<string, ResolvedField>;
+}
+/** Context available inside resolver methods */
+export interface GraphQLContext {
+    /** The original HTTP Request */
+    request: Request;
+    /** Authenticated user (set by auth guards via context.set('user', ...)) */
+    user?: unknown;
+    /** Reference to the HTTP Context for advanced use */
+    httpContext: unknown;
+    /** Allow arbitrary values */
+    [key: string]: unknown;
+}
+/** A GraphQL error entry in the response */
+export interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** The GraphQL response envelope */
+export interface GraphQLResult {
+    data?: Record<string, unknown> | null;
+    errors?: GraphQLError[];
+}
+/**
+ * Pluggable GraphQL execution engine.
+ * Implement this interface to use graphql-js, GraphQL Yoga, Mercurius, etc.
+ *
+ * @example
+ * ```typescript
+ * import * as graphqlJs from 'graphql';
+ * import { GraphQLJsAdapter } from '@buenojs/bueno/graphql';
+ *
+ * GraphQLModule.setup(app, {
+ *   engine: new GraphQLJsAdapter(graphqlJs),
+ *   resolvers: [UserResolver],
+ * });
+ * ```
+ */
+export interface GraphQLEngine {
+    /**
+     * Build the internal schema representation from resolver and type metadata.
+     * Returns an opaque schema object that is passed back to execute().
+     */
+    buildSchema(resolvers: ResolverFieldsByType, types: Map<string, FieldMetadata[]>, sdl: string): unknown;
+    /**
+     * Execute a GraphQL query or mutation.
+     */
+    execute(schema: unknown, query: string, variables: Record<string, unknown>, context: GraphQLContext, operationName?: string): Promise<GraphQLResult>;
+    /**
+     * Execute a GraphQL subscription (optional).
+     * Returns an async generator that yields results.
+     */
+    subscribe?(schema: unknown, query: string, variables: Record<string, unknown>, context: GraphQLContext, operationName?: string): Promise<AsyncGenerator<GraphQLResult>>;
+    /**
+     * Whether this engine supports introspection queries.
+     * Used to determine if the GraphQL Playground should be enabled.
+     */
+    readonly supportsIntrospection: boolean;
+    /**
+     * Whether this engine supports subscriptions.
+     */
+    readonly supportsSubscriptions: boolean;
+}
+/** Resolver fields organized by root type */
+export interface ResolverFieldsByType {
+    queries: Map<string, ResolvedField>;
+    mutations: Map<string, ResolvedField>;
+    subscriptions: Map<string, ResolvedField>;
+}
+/**
+ * Options passed to GraphQLModule.setup()
+ */
+export interface GraphQLModuleOptions {
+    /**
+     * Resolver classes to register.
+     * Dependencies are resolved from the DI container.
+     */
+    resolvers: Constructor[];
+    /**
+     * GraphQL engine adapter (default: built-in lightweight engine).
+     * Use GraphQLJsAdapter for full spec compliance.
+     */
+    engine?: GraphQLEngine;
+    /**
+     * HTTP path for the GraphQL endpoint (default: '/graphql').
+     */
+    path?: string;
+    /**
+     * Enable GraphiQL playground UI at GET <path>.
+     * Default: true when using an engine with supportsIntrospection,
+     *          false when using the built-in engine.
+     * Set to true to force-enable even with the built-in engine (with warning).
+     */
+    playground?: boolean;
+    /**
+     * Serve the SDL at GET <path>/schema (default: true).
+     */
+    introspection?: boolean;
+    /**
+     * Enable WebSocket subscriptions (default: false).
+     * Requires an engine with supportsSubscriptions.
+     */
+    subscriptions?: boolean;
+    /**
+     * Sync @Field metadata to the OpenAPI property store (default: false).
+     * Enables unified types: one class works for both GraphQL and REST/OpenAPI.
+     * Requires @buenojs/bueno/openapi to be in scope.
+     */
+    syncOpenAPI?: boolean;
+    /** Maximum query complexity score (default: 1000) */
+    complexityLimit?: number;
+    /** Maximum query depth (default: 10) */
+    maxDepth?: number;
+}
+/**
+ * GraphQL configuration added to BuenoConfig.
+ */
+export interface GraphQLConfig {
+    /** Enable GraphQL support (default: false) */
+    enabled?: boolean;
+    /** HTTP path (default: '/graphql') */
+    path?: string;
+    /** Enable playground (default: auto) */
+    playground?: boolean;
+    /** Enable introspection SDL endpoint (default: true) */
+    introspection?: boolean;
+    /** Maximum query complexity (default: 1000) */
+    complexityLimit?: number;
+    /** Maximum query depth (default: 10) */
+    maxDepth?: number;
+    /** Enable subscriptions (default: false) */
+    subscriptions?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/graphql/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/graphql/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAIrE;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,OAAO,SAAS,GAChB,OAAO,UAAU,GACjB,OAAO,YAAY,CAAC;AAEvB;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,WAAW,GAAG,WAAW,EAAE,GAAG,aAAa,CAAC;AAIvE;;;GAGG;AACH,qBAAa,SAAS;IACrB,MAAM,CAAC,QAAQ,CAAC,MAAM,QAAQ;CAC9B;AAED;;;GAGG;AACH,qBAAa,UAAU;IACtB,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAS;CAC/B;AAED;;;GAGG;AACH,qBAAa,YAAY;IACxB,MAAM,CAAC,QAAQ,CAAC,MAAM,WAAW;CACjC;AAID,mCAAmC;AACnC,MAAM,WAAW,qBAAqB;IACrC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oCAAoC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAa,SAAQ,qBAAqB;IAC1D,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IACxC,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACrC,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;IAC5C,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,aAAa,EAAE,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACrC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACb;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC3C,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC/C;AAID,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC9B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,6BAA6B;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAID,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAID;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC7B;;;OAGG;IACH,WAAW,CACV,SAAS,EAAE,oBAAoB,EAC/B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,EACnC,GAAG,EAAE,MAAM,GACT,OAAO,CAAC;IAEX;;OAEG;IACH,OAAO,CACN,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,EAAE,cAAc,EACvB,aAAa,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,CACT,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,EAAE,cAAc,EACvB,aAAa,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACxC;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC1C;AAID;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,SAAS,EAAE,WAAW,EAAE,CAAC;IAEzB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IAEvB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB"}

package/dist/health/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Health Check System
+ *
+ * Provides health check endpoints for production monitoring:
+ * - /health (liveness probe) - Returns 200 if server is running
+ * - /ready (readiness probe) - Returns 200 only if all checks pass
+ */
+import type { Middleware } from "../middleware";
+/**
+ * Health check status
+ */
+export type HealthStatus = "healthy" | "unhealthy" | "degraded";
+/**
+ * Individual check result
+ */
+export interface CheckResult {
+    status: HealthStatus;
+    latency?: number;
+    message?: string;
+}
+/**
+ * Overall health check result
+ */
+export interface HealthCheckResult {
+    status: HealthStatus;
+    timestamp: string;
+    version?: string;
+    uptime?: number;
+    checks?: Record<string, CheckResult>;
+}
+/**
+ * Health check function type
+ */
+export type HealthCheckFn = () => Promise<CheckResult> | CheckResult;
+/**
+ * Options for individual health checks
+ */
+export interface CheckOptions {
+    /** Whether this check is critical for readiness (default: true) */
+    critical?: boolean;
+    /** Timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Description of the check */
+    description?: string;
+}
+/**
+ * Options for health middleware
+ */
+export interface HealthMiddlewareOptions {
+    /** Path for liveness probe (default: /health) */
+    healthPath?: string;
+    /** Path for readiness probe (default: /ready) */
+    readyPath?: string;
+    /** Whether to expose metrics in response (default: true) */
+    exposeMetrics?: boolean;
+    /** Initial health checks to register */
+    checks?: Record<string, HealthCheckFn | {
+        fn: HealthCheckFn;
+        options?: CheckOptions;
+    }>;
+    /** Custom version string (default: from package.json) */
+    version?: string;
+}
+/**
+ * Database interface for built-in checker
+ */
+export interface DatabaseLike {
+    query?(sql: string): Promise<unknown>;
+    execute?(sql: string): Promise<unknown>;
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Cache interface for built-in checker
+ */
+export interface CacheLike {
+    get?(key: string): Promise<unknown>;
+    set?(key: string, value: unknown): Promise<unknown>;
+    ping?(): Promise<unknown>;
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Manages health checks for the application
+ */
+export declare class HealthCheckManager {
+    private checks;
+    private startTime;
+    private version;
+    constructor(version?: string);
+    /**
+     * Register a health check
+     */
+    registerCheck(name: string, checkFn: HealthCheckFn, options?: CheckOptions): this;
+    /**
+     * Remove a health check
+     */
+    removeCheck(name: string): boolean;
+    /**
+     * Get all registered check names
+     */
+    getCheckNames(): string[];
+    /**
+     * Check if a check is registered
+     */
+    hasCheck(name: string): boolean;
+    /**
+     * Run a single check with timeout
+     */
+    private runSingleCheck;
+    /**
+     * Execute all registered checks
+     */
+    runChecks(): Promise<Record<string, CheckResult>>;
+    /**
+     * Get liveness status (lightweight - no dependency checks)
+     */
+    getHealth(): HealthCheckResult;
+    /**
+     * Get readiness status (runs all checks)
+     */
+    getReadiness(): Promise<HealthCheckResult>;
+    /**
+     * Get uptime in seconds
+     */
+    getUptime(): number;
+    /**
+     * Reset start time (useful for testing)
+     */
+    resetStartTime(): void;
+}
+/**
+ * Create health check middleware
+ */
+export declare function createHealthMiddleware(options?: HealthMiddlewareOptions): {
+    middleware: Middleware;
+    manager: HealthCheckManager;
+};
+/**
+ * Create a database connectivity check
+ */
+export declare function createDatabaseCheck(db: DatabaseLike, options?: {
+    query?: string;
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create a cache connectivity check
+ */
+export declare function createCacheCheck(cache: CacheLike, options?: {
+    testKey?: string;
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create a custom health check with timeout
+ */
+export declare function createCustomCheck(checkFn: () => Promise<boolean> | boolean, options?: {
+    message?: string;
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create a TCP port check
+ */
+export declare function createTCPCheck(host: string, port: number, options?: {
+    timeout?: number;
+}): HealthCheckFn;
+/**
+ * Create an HTTP endpoint check
+ */
+export declare function createHTTPCheck(url: string, options?: {
+    expectedStatus?: number;
+    timeout?: number;
+    headers?: Record<string, string>;
+}): HealthCheckFn;
+/**
+ * Create a new health check manager
+ */
+export declare function createHealthManager(version?: string): HealthCheckManager;
+//# sourceMappingURL=index.d.ts.map

package/dist/health/index.d.ts.map

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

package/dist/i18n/engine.d.ts

@@ -0,0 +1,105 @@
+/**
+ * i18n Engine — Translation Lookup and Interpolation
+ *
+ * Orchestrates locale loading and exposes the t() translation function.
+ * Handles pluralisation, variable interpolation, fallback, and metrics.
+ */
+import { LocaleNegotiator } from "./negotiator";
+import type { I18nConfig, I18nMetrics, ResolvedI18nConfig, TranslationFunction, TranslationParams } from "./types";
+/**
+ * Main i18n engine.
+ * Handles translation lookup, plural forms, interpolation, and caching.
+ *
+ * Usage:
+ * ```
+ * const i18n = new I18n({ defaultLocale: 'en', supportedLocales: ['en', 'fr'] });
+ * i18n.preload(); // optional
+ * const t = i18n.createTranslator('fr');
+ * console.log(t('greeting', { name: 'Alice' })); // from fr.json
+ * ```
+ */
+export declare class I18n {
+    private loader;
+    private negotiator;
+    readonly config: ResolvedI18nConfig;
+    private metrics;
+    /**
+     * Create an i18n engine.
+     * @param config Optional configuration (all fields are optional)
+     */
+    constructor(config?: I18nConfig);
+    /**
+     * Pre-load all supported locale files at startup.
+     * Optional — lazy loading works without calling this.
+     * Useful for production to catch missing files early.
+     */
+    preload(): void;
+    /**
+     * Enable hot-reload file watching for all supported locales.
+     * Should only be called in development mode.
+     */
+    watchAll(): void;
+    /**
+     * Stop all file watchers.
+     * Call this when the application shuts down.
+     */
+    stopWatching(): void;
+    /**
+     * Return a bound translation function for the given locale.
+     * This is what gets stored on context: ctx.set('t', ...)
+     *
+     * @param locale Locale to create translator for
+     * @returns TranslationFunction bound to that locale
+     */
+    createTranslator(locale: string): TranslationFunction;
+    /**
+     * Primary translation lookup.
+     *
+     * Resolution order:
+     * 1. Check `locale` translations
+     *    a. If `params.count` is provided, try plural key first ({key}_one, {key}_other, etc.)
+     *    b. Then try bare key
+     * 2. If fallbackToDefault and locale !== defaultLocale, repeat step 1 for defaultLocale
+     * 3. Return the key string as last resort
+     *
+     * Metrics are tracked: hits (found in locale), fallbacks (found in default),
+     * misses (returned key string).
+     *
+     * @param locale Locale to translate in
+     * @param key Translation key (supports dot-notation for nested keys)
+     * @param params Optional translation parameters (interpolation + plural count)
+     * @returns Translated string, or key string if not found
+     */
+    t(locale: string, key: string, params?: TranslationParams): string;
+    /**
+     * Returns the LocaleNegotiator instance for use by middleware.
+     * @returns LocaleNegotiator instance
+     */
+    getNegotiator(): LocaleNegotiator;
+    /**
+     * Get current translation metrics.
+     * Useful for debugging and performance monitoring.
+     * @returns Current I18nMetrics
+     */
+    getMetrics(): I18nMetrics;
+    /**
+     * Resolve a translation key in a specific locale.
+     * Returns null if not found (to distinguish from a successful empty string).
+     *
+     * @param locale Locale to resolve in
+     * @param key Translation key
+     * @param params Translation parameters
+     * @param hasCount Whether params contains a count field
+     * @returns Translated string, or null if not found
+     */
+    private _resolve;
+}
+/**
+ * Create an i18n engine.
+ * Convenience factory for new I18n(config).
+ *
+ * @param config Optional configuration
+ * @returns New I18n instance
+ */
+export declare function createI18n(config?: I18nConfig): I18n;
+//# sourceMappingURL=engine.d.ts.map

package/dist/i18n/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/i18n/engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EAEX,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,MAAM,SAAS,CAAC;AAkFjB;;;;;;;;;;;GAWG;AACH,qBAAa,IAAI;IAChB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAAmB;IACrC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,OAAO,CAAC,OAAO,CAMb;IAEF;;;OAGG;gBACS,MAAM,GAAE,UAAe;IAmBnC;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAMhB;;;OAGG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;;;OAMG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB;IAMrD;;;;;;;;;;;;;;;;;OAiBG;IACH,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM;IAkClE;;;OAGG;IACH,aAAa,IAAI,gBAAgB;IAIjC;;;;OAIG;IACH,UAAU,IAAI,WAAW;IASzB;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;CAsBhB;AAID;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAEpD"}

package/dist/i18n/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * i18n Module — Internationalisation for Bueno Framework
+ *
+ * Locale detection (cookie → Accept-Language), translation lookup with
+ * dot-notation keys, variable interpolation, plural forms, and caching.
+ */
+export type { PluralKey, TranslationMap, FlatTranslations, TranslationParams, TranslationFunction, LocaleMatch, I18nContext, I18nConfig, ResolvedI18nConfig, LocaleBundle, I18nMetrics, } from "./types";
+export { I18n, createI18n } from "./engine";
+export { TranslationLoader } from "./loader";
+export { LocaleNegotiator, parseAcceptLanguage, normaliseLocale, } from "./negotiator";
+export { i18nMiddleware, getLocale, getT } from "./middleware";
+export type { I18nMiddlewareOptions } from "./middleware";
+//# sourceMappingURL=index.d.ts.map

package/dist/i18n/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/i18n/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACX,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/i18n/loader.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Translation Loader — JSON File Loading and Caching
+ *
+ * Loads locale JSON files from disk, flattens nested keys to dot-notation,
+ * caches in memory, and supports hot-reload via file watching.
+ */
+import type { LocaleBundle, ResolvedI18nConfig } from "./types";
+/**
+ * Loads and caches locale translation bundles from JSON files.
+ * Supports file watching for hot-reload in development.
+ */
+export declare class TranslationLoader {
+    private cache;
+    private watchers;
+    private config;
+    constructor(config: ResolvedI18nConfig);
+    /**
+     * Load a locale bundle. Returns from cache if already loaded.
+     *
+     * For the default locale:
+     *   - Throws if the file is not found (cannot proceed without defaults)
+     *
+     * For non-default locales:
+     *   - Returns an empty bundle if the file is not found
+     *   - Fallback in the engine will handle the miss
+     *
+     * @param locale Locale identifier to load
+     * @returns LocaleBundle with flattened translations
+     * @throws Error if default locale file is not found
+     */
+    load(locale: string): LocaleBundle;
+    /**
+     * Pre-load all supported locales eagerly.
+     * Call this once at application startup for best performance.
+     *
+     * Non-default locales that are missing are silently skipped
+     * (returning empty bundles).
+     */
+    preload(): void;
+    /**
+     * Invalidate a locale's cache entry.
+     * Forces a reload from disk on the next access.
+     *
+     * @param locale Locale to invalidate
+     */
+    invalidate(locale: string): void;
+    /**
+     * Return all currently loaded locale names.
+     *
+     * @returns Array of loaded locale identifiers
+     */
+    loadedLocales(): string[];
+    /**
+     * Enable file watching for a locale (hot reload in dev mode).
+     * Invalidates cache and reloads on file change.
+     *
+     * @param locale Locale file to watch
+     */
+    watch(locale: string): void;
+    /**
+     * Stop all file watchers.
+     * Call this when the application shuts down.
+     */
+    stopWatching(): void;
+    /**
+     * Resolve the full file path for a locale.
+     * @param locale Locale identifier
+     * @returns Full file path to the locale JSON file
+     */
+    private _resolvePath;
+    /**
+     * Load a locale file from disk and cache it.
+     * @param locale Locale to load
+     * @returns LocaleBundle with flattened translations
+     * @throws Error if default locale file is not found or JSON is invalid
+     */
+    private _loadFromDisk;
+}
+//# sourceMappingURL=loader.d.ts.map

package/dist/i18n/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/i18n/loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAEX,YAAY,EACZ,kBAAkB,EAClB,MAAM,SAAS,CAAC;AAsCjB;;;GAGG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,QAAQ,CAAoD;IACpE,OAAO,CAAC,MAAM,CAAqB;gBAEvB,MAAM,EAAE,kBAAkB;IAItC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAOlC;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;IAiBf;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;OAIG;IACH,aAAa,IAAI,MAAM,EAAE;IAIzB;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAiB3B;;;OAGG;IACH,YAAY,IAAI,IAAI;IASpB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAsCrB"}