@sleepy-hollow/framework 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+export { createRouter, defineRoute, discoverRoutes } from './routing.js';
+import { N as NormalizedRoute } from './types-BC7LJJ6G.js';
+export { H as HTTP_METHODS, a as HttpMethod, R as RouteDiscoveryError, b as RouteHandlerContext, c as RouteModule, d as RouteOperation, e as RoutePrincipal, f as RoutingDiagnostic } from './types-BC7LJJ6G.js';
+import { z } from 'zod';
+export { z } from 'zod';
+export { PreparedRoute, createValidatedRouter, formatValidationDiagnostic, normalizeRoutes, validationDiagnosticResult } from './validation.js';
+export { N as NormalizedBodySchema, a as NormalizedOperationSchemas, b as NormalizedSchema, c as NormalizedValidationRoute, S as SchemaNormalizationError, V as ValidatedRouter, d as ValidationDiagnostic, e as ValidationIssue, f as ValidationLocation, g as ValidationOptions } from './types-DmzdxsaA.js';
+export { AuthProvider, AuthorizationContext, CorsConfiguration, MemoryRateLimiterOptions, NormalizedSecurityRoute, Principal, ProjectSecurityOptions, RateLimitDecision, RateLimitInput, RateLimitPolicy, RateLimiter, RouteSecurity, SecuredHandlerContext, SecurityConfigurationError, SecurityDeclaration, SecurityDiagnostic, SecurityMode, SecurityOptions, SecurityRouter, composeProjectSecurity, createMemoryRateLimiter, createSecurityRouter, defineSecurity, redactSecurityData } from './security.js';
+export { DatabaseConfigurationError, defineResource, openEmbeddedSqlite, openPostgres } from './database.js';
+export { sql } from 'drizzle-orm';
+export { D as DatabaseProfile, E as EmbeddedSqliteDatabase, a as EmbeddedSqliteOptions, P as PostgresDatabase, b as PostgresOptions, R as ResourceDefinition, c as ResourceField, d as ResourceRepository } from './types-BUXw3UwN.js';
+import 'drizzle-orm/better-sqlite3';
+import 'better-sqlite3';
+import 'drizzle-orm/node-postgres';
+import 'pg';
+
+/** The runtime modes a project may be configured for. */
+declare const RUNTIME_MODES: readonly ["development", "test", "preview", "production"];
+/** One of the {@linkcode RUNTIME_MODES} a process may run in. */
+type RuntimeMode = (typeof RUNTIME_MODES)[number];
+/** One schema per runtime mode: what configuration that mode requires. */
+type ModeSchemas = Readonly<Record<RuntimeMode, z.ZodObject>>;
+/**
+ * A project's configuration contract.
+ *
+ * Each mode carries its own schema, so production can demand values that
+ * development supplies a default for, and the difference is stated rather than
+ * discovered on deployment.
+ */
+interface ConfigurationDefinition<Schemas extends ModeSchemas> {
+    /** The schema each runtime mode must satisfy. */
+    readonly modes: Schemas;
+    /** Keys whose values are redacted from metadata and logs. */
+    readonly sensitiveKeys?: readonly string[];
+    /** Env files read in the named modes; never consulted in production. */
+    readonly localEnvFiles?: Readonly<Partial<Record<"development" | "test", string>>>;
+}
+/** One reason configuration could not be resolved. */
+interface ConfigurationDiagnostic {
+    /** Stable machine-readable identifier for this kind of fault. */
+    readonly code: string;
+    /** Configuration faults are always fatal; there are no warnings. */
+    readonly severity: "error";
+    /** The mode being resolved, when the fault is specific to one. */
+    readonly mode?: RuntimeMode;
+    /** The configuration key concerned; omitted for whole-shape faults. */
+    readonly key?: string;
+    /** What was required of the value. */
+    readonly expected: string;
+    /** What to change to resolve it. */
+    readonly correction: string;
+}
+/**
+ * Thrown when configuration cannot be resolved.
+ *
+ * Raised at startup rather than at first use, so a missing value stops the
+ * process instead of failing the first request that happens to need it. The
+ * message names keys but never their values, which may be secrets.
+ */
+declare class ConfigurationError extends Error {
+    readonly diagnostics: readonly ConfigurationDiagnostic[];
+    /**
+     * Builds an error whose message lists every diagnostic, one per line.
+     *
+     * @param diagnostics Every fault found, in the order detected.
+     */
+    constructor(diagnostics: readonly ConfigurationDiagnostic[]);
+}
+/** Where one configuration key's value came from, without the value. */
+interface ConfigurationKeyMetadata {
+    /** The key's name. */
+    readonly name: string;
+    /** Which source supplied it, or `absent` when nothing did. */
+    readonly source: "absent" | "default" | "env-file" | "environment";
+    /** Whether a value was supplied at all. */
+    readonly present: boolean;
+    /** Whether the key was declared sensitive, and so never reported. */
+    readonly sensitive: boolean;
+}
+/**
+ * Provenance for a resolved configuration: which keys were set and from where,
+ * safe to log because it carries no values.
+ */
+interface ConfigurationMetadata<M extends RuntimeMode = RuntimeMode> {
+    /** The mode this configuration was resolved for. */
+    readonly mode: M;
+    /** One entry per declared key. */
+    readonly keys: readonly ConfigurationKeyMetadata[];
+}
+/** How to resolve configuration, and where to read it from. */
+interface ResolveConfigurationOptions<M extends RuntimeMode> {
+    /** The mode to resolve for. */
+    readonly mode: M;
+    /** Environment to read; defaults to the process environment. */
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    /** Reads env files; supply your own to resolve without disk access. */
+    readonly readTextFile?: (path: string) => Promise<string>;
+}
+/** Configuration after resolution: the values, and where they came from. */
+interface ResolvedConfiguration<M extends RuntimeMode, Values> {
+    /** The mode these values were resolved for. */
+    readonly mode: M;
+    /** The parsed values, typed by that mode's schema. */
+    readonly values: Readonly<Values>;
+    /** Provenance for each key, without values. */
+    readonly metadata: ConfigurationMetadata<M>;
+}
+/** The value type a definition yields in a given mode. */
+type ConfigurationValues<Definition extends ConfigurationDefinition<ModeSchemas>, M extends RuntimeMode> = z.output<Definition["modes"][M]>;
+/** Severity of a log line. */
+type LogLevel = "debug" | "error" | "info" | "warn";
+/** How to build a JSON logger. */
+interface JsonLoggerOptions {
+    /** The mode being run in; recorded on every line. */
+    readonly mode: RuntimeMode;
+    /** Receives each serialized line. */
+    readonly sink: (line: string) => void;
+    /** Supplies timestamps; override to make log output deterministic. */
+    readonly clock?: () => Date;
+    /** Field names redacted from every line's context. */
+    readonly sensitiveFields?: readonly string[];
+}
+/**
+ * A logger that emits one JSON object per line.
+ *
+ * Declared sensitive fields are redacted from context before serialization, so
+ * a secret passed to a log call does not reach the sink.
+ */
+interface JsonLogger {
+    /**
+     * Logs at debug severity.
+     *
+     * @param event Stable event name, not a sentence.
+     * @param context Structured detail; sensitive fields are redacted.
+     */
+    debug(event: string, context?: unknown): void;
+    /**
+     * Logs at info severity.
+     *
+     * @param event Stable event name, not a sentence.
+     * @param context Structured detail; sensitive fields are redacted.
+     */
+    info(event: string, context?: unknown): void;
+    /**
+     * Logs at warning severity.
+     *
+     * @param event Stable event name, not a sentence.
+     * @param context Structured detail; sensitive fields are redacted.
+     */
+    warn(event: string, context?: unknown): void;
+    /**
+     * Logs at error severity.
+     *
+     * @param event Stable event name, not a sentence.
+     * @param context Structured detail; sensitive fields are redacted.
+     */
+    error(event: string, context?: unknown): void;
+    /**
+     * Derives a logger that stamps every line with a request identifier.
+     *
+     * @param requestId Correlates lines belonging to one request.
+     * @returns A logger writing to the same sink.
+     */
+    withRequest(requestId: string): JsonLogger;
+}
+/** One dependency readiness probes before reporting the process ready. */
+interface ReadinessCheck {
+    /** Names the dependency in the readiness response. */
+    readonly name: string;
+    /** How long this check may take before it counts as failed. */
+    readonly timeoutMs: number;
+    /**
+     * Probes the dependency.
+     *
+     * @param signal Aborts when the check exceeds its timeout.
+     * @returns Whether the dependency is usable.
+     */
+    check(signal: AbortSignal): Promise<boolean>;
+}
+/** Which operational endpoints to expose, and what they report. */
+interface OperationalRouteOptions {
+    /** Path of the liveness endpoint. */
+    readonly healthPath: string;
+    /** Reports whether the process itself is healthy; defaults to always. */
+    readonly isHealthy?: () => boolean;
+    /** Path of the readiness endpoint; omit to expose liveness only. */
+    readonly readinessPath?: string;
+    /** Dependencies probed before reporting ready. */
+    readonly readiness?: readonly ReadinessCheck[];
+}
+
+/**
+ * Declares what configuration each runtime mode requires.
+ *
+ * The definition itself is validated here, so a mode missing a schema or a
+ * sensitive key naming nothing is caught before any value is read.
+ *
+ * @param definition The per-mode schemas, sensitive keys, and env files.
+ * @returns The validated definition, for {@linkcode resolveConfiguration}.
+ * @throws {ConfigurationError} When the definition is malformed.
+ */
+declare function defineConfiguration<const Schemas extends ModeSchemas>(definition: ConfigurationDefinition<Schemas>): ConfigurationDefinition<Schemas>;
+/**
+ * Resolves configuration for one mode, from env files and the environment.
+ *
+ * Every fault is collected and thrown together, so one startup reports the
+ * whole set of missing or malformed values rather than the first. Env files
+ * are consulted only in the modes the definition names, never in production.
+ *
+ * @param definition The contract, from {@linkcode defineConfiguration}.
+ * @param options The mode to resolve, and where to read values from.
+ * @returns The parsed values, and provenance for each key.
+ * @throws {ConfigurationError} When any required value is missing or invalid.
+ */
+declare function resolveConfiguration<const Schemas extends ModeSchemas, const M extends RuntimeMode>(definition: ConfigurationDefinition<Schemas>, options: ResolveConfigurationOptions<M>): Promise<ResolvedConfiguration<M, ConfigurationValues<ConfigurationDefinition<Schemas>, M>>>;
+
+/**
+ * Builds a logger that writes one JSON object per line.
+ *
+ * Fields named as sensitive are redacted before serialization, so a secret
+ * passed in context never reaches the sink.
+ *
+ * @param options The mode, the sink, and which fields to redact.
+ * @returns A logger, derivable per request with `withRequest`.
+ */
+declare function createJsonLogger(options: JsonLoggerOptions): JsonLogger;
+
+/**
+ * Builds liveness and readiness routes, ready to add to the route table.
+ *
+ * Liveness answers whether the process is up; readiness probes the declared
+ * dependencies, each under its own timeout, and reports which one failed. A
+ * probe that exceeds its timeout counts as failed rather than hanging.
+ *
+ * @param options The paths to expose, and the dependencies to probe.
+ * @returns Routes to include alongside the discovered ones.
+ * @throws {ConfigurationError} When a path or readiness check is malformed.
+ */
+declare function createOperationalRoutes(options: OperationalRouteOptions): readonly NormalizedRoute[];
+
+export { type ConfigurationDefinition, type ConfigurationDiagnostic, ConfigurationError, type ConfigurationKeyMetadata, type ConfigurationMetadata, type ConfigurationValues, type JsonLogger, type JsonLoggerOptions, type LogLevel, type ModeSchemas, NormalizedRoute, type OperationalRouteOptions, RUNTIME_MODES, type ReadinessCheck, type ResolveConfigurationOptions, type ResolvedConfiguration, type RuntimeMode, createJsonLogger, createOperationalRoutes, defineConfiguration, resolveConfiguration };

package/dist/index.js

@@ -0,0 +1,71 @@
+import {
+  ConfigurationError,
+  RUNTIME_MODES,
+  createJsonLogger,
+  createOperationalRoutes,
+  defineConfiguration,
+  resolveConfiguration
+} from "./chunk-BJONRVDG.js";
+import {
+  DatabaseConfigurationError,
+  defineResource,
+  openEmbeddedSqlite,
+  openPostgres,
+  sql
+} from "./chunk-BAKXP7IR.js";
+import {
+  SecurityConfigurationError,
+  composeProjectSecurity,
+  createMemoryRateLimiter,
+  createSecurityRouter,
+  defineSecurity,
+  redactSecurityData
+} from "./chunk-DGTHFZPZ.js";
+import {
+  SchemaNormalizationError,
+  createValidatedRouter,
+  formatValidationDiagnostic,
+  normalizeRoutes,
+  validationDiagnosticResult,
+  z
+} from "./chunk-CAPFDC25.js";
+import {
+  HTTP_METHODS,
+  RouteDiscoveryError,
+  createRouter,
+  defineRoute,
+  discoverRoutes
+} from "./chunk-53TZY5YP.js";
+import "./chunk-LNJDFJGT.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  ConfigurationError,
+  DatabaseConfigurationError,
+  HTTP_METHODS,
+  RUNTIME_MODES,
+  RouteDiscoveryError,
+  SchemaNormalizationError,
+  SecurityConfigurationError,
+  composeProjectSecurity,
+  createJsonLogger,
+  createMemoryRateLimiter,
+  createOperationalRoutes,
+  createRouter,
+  createSecurityRouter,
+  createValidatedRouter,
+  defineConfiguration,
+  defineResource,
+  defineRoute,
+  defineSecurity,
+  discoverRoutes,
+  formatValidationDiagnostic,
+  normalizeRoutes,
+  openEmbeddedSqlite,
+  openPostgres,
+  redactSecurityData,
+  resolveConfiguration,
+  sql,
+  validationDiagnosticResult,
+  z
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}