@ubean/server 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,492 @@
+import { Hookable } from "hookable";
+import { Context, MiddlewareHandler, Next } from "hono";
+import { RouteRule, RouteRule as RouteRule$1, Span, Span as Span$1, SpanAttributes, SpanAttributes as SpanAttributes$1, SpanContext, SpanEndOptions, SpanEvent, SpanOptions, SpanOptions as SpanOptions$1, SpanStatus, UbeanBindings, UbeanContext, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanVariables } from "@ubean/types";
+//#region src/cache.d.ts
+interface CacheEntry {
+  body: ArrayBuffer;
+  headers: Record<string, string>;
+  status: number;
+  statusText: string;
+  createdAt: number;
+  expiresAt: number;
+}
+interface CacheStore {
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: Omit<CacheEntry, 'createdAt' | 'expiresAt'>, ttl: number): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+declare function createMemoryStore(maxEntries?: number): CacheStore;
+declare function useCacheStore(store?: CacheStore): CacheStore;
+declare function clearCacheStore(): void;
+interface CacheRule {
+  ttl: number;
+  swr?: boolean | number;
+  name?: string;
+}
+declare function createCacheMiddleware(options?: {
+  store?: CacheStore;
+  rules?: Record<string, CacheRule>;
+  defaultTtl?: number;
+}): (c: Context, next: Next) => Promise<Response | undefined>;
+declare function cachedEventHandler<T extends (c: Context) => Response | Promise<Response>>(handler: T, options?: CacheRule): T;
+declare function invalidateRouteCache(keyPattern?: string | RegExp): Promise<void>;
+declare function resolveRouteCacheRules(routeRules: Record<string, RouteRule$1>): Record<string, CacheRule>;
+//#endregion
+//#region src/database.d.ts
+interface DatabaseHooks {
+  'db:connect': (db: Database) => void | Promise<void>;
+  'db:disconnect': (db: Database) => void | Promise<void>;
+  'db:query': (query: string, params?: unknown[]) => void | Promise<void>;
+  'db:error': (error: Error, query?: string) => void | Promise<void>;
+}
+interface Database {
+  sql: <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]) => Promise<{
+    rows: T[];
+  }>;
+  exec: (query: string) => Promise<void>;
+  close: () => Promise<void>;
+}
+interface DatabaseConnector {
+  (options?: Record<string, unknown>): DatabaseConnectorInstance;
+}
+interface DatabaseConnectorInstance {
+  dialect?: string;
+  [key: string]: unknown;
+}
+interface DrizzleConfig {
+  schema?: Record<string, unknown>;
+  logger?: boolean | {
+    logQuery?: (query: string, params: unknown[]) => void;
+  };
+  casing?: 'camelCase' | 'snake_case';
+}
+interface DatabaseOptions {
+  connector?: DatabaseConnectorInstance;
+  connectors?: Record<string, DatabaseConnectorInstance>;
+  default?: string;
+}
+interface Migration {
+  name: string;
+  up: string;
+  down?: string;
+}
+declare const RAW_SQL: unique symbol;
+interface RawSqlValue {
+  [RAW_SQL]: true;
+  value: string;
+}
+declare function rawSql(str: string): RawSqlValue;
+type RawSqlFn = <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]) => Promise<{
+  rows: T[];
+}>;
+type RawExecFn = (query: string) => Promise<void>;
+type RawCloseFn = () => Promise<void>;
+declare function defineDatabase(options?: DatabaseOptions): Database;
+declare function useDatabase(name?: string): Database;
+declare function closeDatabases(): Promise<void>;
+declare function getDatabaseHooks(): import("hookable").Hookable<DatabaseHooks, import("hookable").HookKeys<DatabaseHooks>>;
+declare function registerDb0Create(fn: (connector: DatabaseConnectorInstance) => {
+  sql: RawSqlFn;
+  exec: RawExecFn;
+  close: RawCloseFn;
+}): void;
+declare function migrateDatabase(db: Database, migrations: string[]): Promise<void>;
+declare function runMigrations(db: Database, migrations: Migration[], options?: {
+  table?: string;
+  log?: boolean;
+}): Promise<{
+  applied: string[];
+}>;
+//#endregion
+//#region src/queue.d.ts
+interface QueueMessage<T = unknown> {
+  id: string;
+  body: T;
+  timestamp: number;
+  attempts: number;
+  headers?: Record<string, string>;
+}
+interface QueueHandler<T = unknown> {
+  (message: QueueMessage<T>): void | Promise<void>;
+}
+interface QueueOptions<T = unknown> {
+  name: string;
+  handler?: QueueHandler<T>;
+  concurrency?: number;
+  retries?: number;
+  retryDelay?: number;
+  deadLetterQueue?: string;
+}
+interface QueueDefinition<T = unknown> extends QueueOptions<T> {
+  handler: QueueHandler<T>;
+}
+interface QueueDriver {
+  send<T>(queueName: string, message: T, options?: SendOptions): Promise<string>;
+  sendBatch<T>(queueName: string, messages: T[], options?: SendOptions): Promise<string[]>;
+  registerHandler?(queueName: string, handler: QueueHandler, options?: QueueOptions): void;
+  start?(): Promise<void>;
+  stop?(): Promise<void>;
+  getQueueDepth?(queueName: string): Promise<number>;
+  deleteMessage?(queueName: string, messageId: string): Promise<boolean>;
+}
+interface SendOptions {
+  delay?: number;
+  headers?: Record<string, string>;
+}
+interface QueueStats {
+  pending: number;
+  processing: number;
+  completed: number;
+  failed: number;
+}
+declare function defineQueue<T = unknown>(options: QueueOptions<T>, handler?: QueueHandler<T>): QueueDefinition<T>;
+declare function createMemoryQueueDriver(): QueueDriver;
+declare function useQueueDriver(): QueueDriver;
+declare function setQueueDriver(driver: QueueDriver): void;
+declare function sendMessage<T = unknown>(queueName: string, body: T, options?: SendOptions): Promise<string>;
+declare function sendMessages<T = unknown>(queueName: string, bodies: T[], options?: SendOptions): Promise<string[]>;
+declare function getQueueDefinitions(): QueueDefinition[];
+declare function clearQueueDefinitions(): void;
+declare function startQueueWorkers(): Promise<void>;
+declare function stopQueueWorkers(): Promise<void>;
+declare function getQueueStats(queueName: string): QueueStats | undefined;
+declare function getAllQueueStats(): Record<string, QueueStats>;
+//#endregion
+//#region src/cron.d.ts
+type CronSchedule = string;
+interface CronTaskMeta {
+  name: string;
+  schedule: CronSchedule;
+  description?: string;
+  timezone?: string;
+  timeout?: number;
+  runOnStart?: boolean;
+}
+interface CronTaskDefinition extends CronTaskMeta {
+  handler: (ctx: CronContext) => void | Promise<void>;
+}
+interface CronContext {
+  name: string;
+  schedule: CronSchedule;
+  timestamp: Date;
+  runCount: number;
+}
+interface ScheduledTask {
+  name: string;
+  schedule: CronSchedule;
+  handler: (ctx: CronContext) => void | Promise<void>;
+  meta: Omit<CronTaskMeta, 'name' | 'schedule'>;
+}
+declare function defineScheduled(metaOrName: CronTaskMeta | string, handler?: (ctx: CronContext) => void | Promise<void>): ScheduledTask;
+declare function getScheduledTasks(): ScheduledTask[];
+declare function clearScheduledTasks(): void;
+declare function runScheduledTask(name: string): Promise<{
+  ok: boolean;
+  duration: number;
+  error?: Error;
+}>;
+declare function createCronContext(name: string, schedule: string): CronContext;
+//#endregion
+//#region src/cron-scheduler.d.ts
+interface CronScheduler {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  runTask(name: string): Promise<{
+    ok: boolean;
+    duration: number;
+    error?: Error;
+  }>;
+  isRunning(): boolean;
+  getTasks(): ScheduledTask[];
+  getNextRuns(): Array<{
+    name: string;
+    nextRun: Date | null;
+  }>;
+}
+interface SchedulerOptions {
+  timezone?: string;
+  defaultTimeout?: number;
+  onTaskStart?: (task: ScheduledTask) => void;
+  onTaskComplete?: (task: ScheduledTask, result: {
+    ok: boolean;
+    duration: number;
+    error?: Error;
+  }) => void;
+  onTaskError?: (task: ScheduledTask, error: Error) => void;
+}
+type CronField = number[];
+interface ParsedCron {
+  minute: CronField;
+  hour: CronField;
+  dom: CronField;
+  month: CronField;
+  dow: CronField;
+}
+declare function parseCron(schedule: string): ParsedCron | null;
+declare function createMemoryCronScheduler(options?: SchedulerOptions): CronScheduler;
+declare function startCronScheduler(options?: SchedulerOptions): CronScheduler;
+declare function resetCronRunCounts(): void;
+declare function validateCron(schedule: string): boolean;
+//#endregion
+//#region src/websocket.d.ts
+interface Peer {
+  readonly id: string;
+  readonly url: string;
+  readonly headers: Headers;
+  readonly readyState: number;
+  send(data: string | ArrayBuffer | Uint8Array): void;
+  publish(topic: string, data: string | ArrayBuffer | Uint8Array): void;
+  subscribe(topic: string): void;
+  unsubscribe(topic: string): void;
+  close(code?: number, reason?: string): void;
+  getData<T = unknown>(): T | undefined;
+  setData<T>(data: T): void;
+}
+interface WebSocketRoom {
+  readonly name: string;
+  readonly peers: Set<Peer>;
+  broadcast(data: string | ArrayBuffer | Uint8Array, options?: {
+    except?: Peer;
+  }): void;
+  add(peer: Peer): void;
+  remove(peer: Peer): void;
+}
+interface WebSocketHooks {
+  open?: (peer: Peer) => void | Promise<void>;
+  message?: (peer: Peer, message: string | ArrayBuffer) => void | Promise<void>;
+  close?: (peer: Peer, code: number, reason: string) => void | Promise<void>;
+  error?: (peer: Peer, error: Error) => void | Promise<void>;
+}
+interface WebSocketDefinition {
+  path?: string;
+  hooks?: WebSocketHooks;
+  topics?: string[];
+  rooms?: string[];
+}
+declare function createRoom(name: string): WebSocketRoom;
+declare function defineWebSocket(def: WebSocketDefinition): WebSocketDefinition;
+declare function defineRoom(name: string): WebSocketRoom;
+declare function getRoom(name: string): WebSocketRoom | undefined;
+declare function getRooms(): Map<string, WebSocketRoom>;
+declare function broadcast(topic: string, data: string | ArrayBuffer | Uint8Array): void;
+declare function registerWebSocket(path: string, def: WebSocketDefinition): void;
+declare function getWebSocketDefinitions(): Map<string, WebSocketDefinition>;
+interface UpgradeResult {
+  response: Response;
+  peer: Peer;
+}
+declare function handleUpgrade(c: Context<UbeanEnv$1>, options: {
+  send: (data: string | ArrayBuffer | Uint8Array) => void;
+  close: (code?: number, reason?: string) => void;
+  raw?: unknown;
+}): UpgradeResult;
+declare function handleMessage(peer: Peer, message: string | ArrayBuffer): void;
+declare function handleClose(peer: Peer, code?: number, reason?: string): void;
+declare function handleError(peer: Peer, error: Error): void;
+declare function createWebSocketMiddleware(): MiddlewareHandler<UbeanEnv$1>;
+declare function clearWebSocketState(): void;
+//#endregion
+//#region src/sse.d.ts
+interface SSEMessage {
+  data?: string | object;
+  event?: string;
+  id?: string;
+  retry?: number;
+  comment?: string;
+}
+interface SSEConnection {
+  readonly id: string;
+  send(message: SSEMessage): void;
+  sendData(data: string | object, event?: string): void;
+  comment(text: string): void;
+  close(): void;
+  readonly closed: boolean;
+}
+interface SSEHandler {
+  onConnect?: (connection: SSEConnection) => void | Promise<void>;
+  onClose?: (connection: SSEConnection) => void | Promise<void>;
+}
+interface SSEOptions {
+  headers?: Record<string, string>;
+  retry?: number;
+  keepAlive?: boolean | number;
+}
+declare function formatSSEMessage(msg: SSEMessage): string;
+declare function createSSEStream(c: Context<UbeanEnv$1>, handler: SSEHandler, options?: SSEOptions): Response;
+declare function defineSSE(handler: SSEHandler, options?: SSEOptions): MiddlewareHandler<UbeanEnv$1>;
+declare function getSSEConnections(): Map<string, SSEConnection>;
+declare function broadcastSSE(event: string, data: string | object, filter?: (conn: SSEConnection) => boolean): void;
+declare function closeAllSSE(): void;
+declare function sseHeaders(): Record<string, string>;
+declare function clearSSEState(): void;
+//#endregion
+//#region src/storage.d.ts
+interface StorageDriver {
+  getItemRaw(key: string): Promise<unknown>;
+  setItemRaw(key: string, value: unknown): Promise<void>;
+  removeItem(key: string): Promise<void>;
+  getKeys(base?: string): Promise<string[]>;
+  clear(base?: string): Promise<void>;
+  hasItem(key: string): Promise<boolean>;
+}
+interface UbeanStorage {
+  get<T = unknown>(key: string): Promise<T | null>;
+  set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+  remove(key: string): Promise<void>;
+  keys(base?: string): Promise<string[]>;
+  clear(base?: string): Promise<void>;
+  has(key: string): Promise<boolean>;
+  getMeta(key: string): Promise<{
+    ttl?: number;
+    createdAt?: number;
+    expiresAt?: number;
+  } | null>;
+  mount(base: string, driver: StorageDriver): void;
+}
+declare function createMemoryDriver(): StorageDriver;
+declare function createStorage(options?: {
+  driver?: StorageDriver;
+  base?: string;
+}): UbeanStorage;
+declare function useStorage(storage?: UbeanStorage): UbeanStorage;
+declare function clearGlobalStorage(): void;
+interface KVOptions<T = unknown> {
+  ttl?: number;
+  prefix?: string;
+  serialize?: (value: T) => string;
+  deserialize?: (raw: string) => T;
+}
+interface KVNamespace<T = unknown> {
+  get(key: string): Promise<T | null>;
+  set(key: string, value: T, ttl?: number): Promise<void>;
+  remove(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+  has(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+declare function createKV<T = unknown>(options?: KVOptions<T>): KVNamespace<T>;
+declare function useKV<T = unknown>(name?: string, options?: KVOptions<T>): KVNamespace<T>;
+//#endregion
+//#region src/observability.d.ts
+declare const REQUEST_ID_HEADER = "x-request-id";
+interface RequestIdOptions {
+  headerName?: string;
+  limitLength?: number;
+  generator?: (c: any) => string;
+}
+declare function generateRequestId(): string;
+declare function getRequestId(c: {
+  get: (key: 'requestId') => string;
+}): string;
+interface ObservabilityHooks {
+  'span:start': (span: Span$1) => void | Promise<void>;
+  'span:end': (span: Span$1) => void | Promise<void>;
+  'span:error': (span: Span$1, error: Error) => void | Promise<void>;
+}
+interface ObservabilityExporter {
+  name: string;
+  exportSpan(span: Readonly<Span$1>): void | Promise<void>;
+  flush?(): Promise<void>;
+  shutdown?(): Promise<void>;
+}
+interface ObservabilityConfig {
+  defaultAttributes?: SpanAttributes$1;
+  sensitiveKeys?: string[];
+  exporters?: ObservabilityExporter[];
+  enabled?: boolean;
+}
+declare function createSpan(options: SpanOptions$1): Span$1;
+declare function createObservabilityTracer(config?: ObservabilityConfig): {
+  hooks: Hookable<ObservabilityHooks, import("hookable").HookKeys<ObservabilityHooks>>;
+  startSpan: (options: SpanOptions$1) => Span$1;
+  withSpan: <T>(options: SpanOptions$1 | string, fn: (span: Span$1) => T | Promise<T>) => Promise<T>;
+  getActiveSpan: () => Span$1 | undefined;
+  addExporter: (exporter: ObservabilityExporter) => void;
+  removeExporter: (name: string) => void;
+  redactAttributes: (attrs: SpanAttributes$1) => SpanAttributes$1;
+  flush: () => Promise<void>;
+  shutdown: () => Promise<void>;
+  createSpan: typeof createSpan;
+};
+type ObservabilityTracer = ReturnType<typeof createObservabilityTracer>;
+declare function setGlobalTracer(tracer: ObservabilityTracer | null): void;
+declare function getGlobalTracer(): ObservabilityTracer;
+declare function startSpan(options: SpanOptions$1 | string): Span$1;
+declare function withSpan<T>(options: SpanOptions$1 | string, fn: (span: Span$1) => T | Promise<T>): Promise<T>;
+declare function createOpenTelemetryExporter(options?: {
+  url?: string;
+  headers?: Record<string, string>;
+  serviceName?: string;
+  serviceVersion?: string;
+  fetchImpl?: typeof fetch;
+}): ObservabilityExporter;
+declare function createConsoleExporter(options?: {
+  colors?: boolean;
+  slowThreshold?: number;
+}): ObservabilityExporter;
+interface TracingMiddlewareOptions {
+  tracer?: ObservabilityTracer;
+  includeHeaders?: boolean;
+  headerFilter?: (name: string) => boolean;
+}
+declare function createTracingMiddleware(options?: TracingMiddlewareOptions): (c: any, next: any) => Promise<void>;
+declare function getSpan(c: {
+  get: (key: string) => unknown;
+}): Span$1 | undefined;
+//#endregion
+//#region src/static.d.ts
+interface ServeStaticOptions {
+  publicDir: string;
+  indexFiles?: string[];
+  maxAge?: number;
+}
+declare function serveStatic(options: ServeStaticOptions): MiddlewareHandler<UbeanEnv$1>;
+//#endregion
+//#region src/cors.d.ts
+interface CorsOptions {
+  origin?: string | string[] | boolean | ((origin: string, c: Context<UbeanEnv$1>) => boolean | string | undefined | Promise<boolean | string | undefined>);
+  allowMethods?: string[];
+  allowHeaders?: string[];
+  exposeHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+}
+declare function createCorsMiddleware(options?: CorsOptions): MiddlewareHandler<UbeanEnv$1>;
+declare function defineCors(options: CorsOptions): MiddlewareHandler<UbeanEnv$1>;
+//#endregion
+//#region src/rate-limit.d.ts
+interface RateLimitOptions {
+  maxRequests?: number;
+  windowMs?: number;
+  keyGenerator?: (c: Context<UbeanEnv$1>) => string;
+  handler?: (c: Context<UbeanEnv$1>, info: RateLimitInfo) => Response | Promise<Response>;
+  skip?: (c: Context<UbeanEnv$1>) => boolean | Promise<boolean>;
+  standardHeaders?: boolean;
+  legacyHeaders?: boolean;
+  store?: RateLimitStore;
+}
+interface RateLimitInfo {
+  limit: number;
+  remaining: number;
+  reset: number;
+  retryAfter: number;
+}
+interface RateLimitStoreEntry {
+  count: number;
+  resetAt: number;
+}
+interface RateLimitStore {
+  get(key: string): Promise<RateLimitStoreEntry | undefined>;
+  set(key: string, entry: RateLimitStoreEntry, ttlMs: number): Promise<void>;
+  increment(key: string, windowMs: number): Promise<RateLimitStoreEntry>;
+  reset(key: string): Promise<void>;
+}
+declare function createRateLimitMiddleware(options?: RateLimitOptions): MiddlewareHandler<UbeanEnv$1>;
+declare function defineRateLimit(options: RateLimitOptions): MiddlewareHandler<UbeanEnv$1>;
+declare function createMemoryRateLimitStore(): RateLimitStore & {
+  destroy(): void;
+};
+//#endregion
+export { type CacheEntry, type CacheRule, type CacheStore, type CorsOptions, type CronContext, type CronSchedule, type CronScheduler, type CronTaskDefinition, type CronTaskMeta, type Database, type DatabaseConnector, type DatabaseConnectorInstance, type DatabaseHooks, type DatabaseOptions, type DrizzleConfig, type KVNamespace, type KVOptions, type Migration, type ObservabilityConfig, type ObservabilityExporter, type ObservabilityHooks, type ObservabilityTracer, type Peer, type QueueDefinition, type QueueDriver, type QueueHandler, type QueueMessage, type QueueOptions, type QueueStats, REQUEST_ID_HEADER, type RateLimitInfo, type RateLimitOptions, type RateLimitStore, type RateLimitStoreEntry, type RequestIdOptions, type RouteRule, type SSEConnection, type SSEHandler, type SSEMessage, type SSEOptions, type ScheduledTask, type SchedulerOptions, type SendOptions, type ServeStaticOptions, type Span, type SpanAttributes, type SpanContext, type SpanEndOptions, type SpanEvent, type SpanOptions, type SpanStatus, type StorageDriver, type TracingMiddlewareOptions, type UbeanBindings, type UbeanContext, type UbeanEnv, type UbeanStorage, type UbeanVariables, type UpgradeResult, type WebSocketDefinition, type WebSocketHooks, type WebSocketRoom, broadcast, broadcastSSE, cachedEventHandler, clearCacheStore, clearGlobalStorage, clearQueueDefinitions, clearSSEState, clearScheduledTasks, clearWebSocketState, closeAllSSE, closeDatabases, createCacheMiddleware, createConsoleExporter, createCorsMiddleware, createCronContext, createKV, createMemoryCronScheduler, createMemoryDriver, createMemoryQueueDriver, createMemoryRateLimitStore, createMemoryStore, createObservabilityTracer, createOpenTelemetryExporter, createRateLimitMiddleware, createRoom, createSSEStream, createSpan, createStorage, createTracingMiddleware, createWebSocketMiddleware, defineCors, defineDatabase, defineQueue, defineRateLimit, defineRoom, defineSSE, defineScheduled, defineWebSocket, formatSSEMessage, generateRequestId, getAllQueueStats, getDatabaseHooks, getGlobalTracer, getQueueDefinitions, getQueueStats, getRequestId, getRoom, getRooms, getSSEConnections, getScheduledTasks, getSpan, getWebSocketDefinitions, handleClose, handleError, handleMessage, handleUpgrade, invalidateRouteCache, migrateDatabase, parseCron, rawSql as raw, rawSql, rawSql as sqlRaw, registerDb0Create, registerWebSocket, resetCronRunCounts, resolveRouteCacheRules, runMigrations, runScheduledTask, sendMessage, sendMessages, serveStatic, setGlobalTracer, setQueueDriver, sseHeaders, startCronScheduler, startQueueWorkers, startSpan, stopQueueWorkers, useCacheStore, useDatabase, useKV, useQueueDriver, useStorage, validateCron, withSpan };