@stacksjs/types 0.70.88 → 0.70.91

package/dist/realtime.d.ts

@@ -0,0 +1,443 @@
+/**
+ * Realtime configuration presets for common use cases
+ */
+export declare const RealtimePresets: {
+  /**
+   * Server mode presets (ts-broadcasting)
+   */
+  server: {
+  /**
+     * Development preset - minimal config, debug enabled
+     */
+  development: {
+  enabled: true;
+  mode: 'server';
+  debug: true;
+  server: {
+  host: 'localhost';
+  port: 6001;
+  scheme: 'ws';
+  driver: 'bun';
+  rateLimit: {
+  enabled: false
+};
+  healthCheck: {
+  enabled: true;
+  path: '/health'
+}
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: true
+}
+};
+  /**
+     * Production preset - optimized for production workloads
+     */
+  production: {
+  enabled: true;
+  mode: 'server';
+  debug: false;
+  server: {
+  host: '0.0.0.0';
+  port: 6001;
+  scheme: 'wss';
+  driver: 'bun';
+  redis: {
+  enabled: true;
+  prefix: 'stacks:realtime:'
+};
+  rateLimit: {
+  enabled: true;
+  maxConnectionsPerIp: 100;
+  maxMessagesPerSecond: 50;
+  maxPayloadSize: 65536
+};
+  loadManagement: {
+  maxConnections: 10000;
+  backpressureThreshold: 1000;
+  messageQueueSize: 10000;
+  gracefulShutdownTimeout: 30000
+};
+  autoScaling: {
+  min: 2;
+  max: 10;
+  targetCPU: 70
+};
+  healthCheck: {
+  enabled: true;
+  path: '/health';
+  interval: 30
+};
+  metrics: {
+  enabled: true;
+  port: 9090;
+  path: '/metrics'
+}
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: true
+}
+};
+  /**
+     * High performance preset - optimized for high throughput
+     */
+  highPerformance: {
+  enabled: true;
+  mode: 'server';
+  server: {
+  driver: 'bun';
+  redis: {
+  enabled: true;
+  cluster: true
+};
+  rateLimit: {
+  enabled: true;
+  maxConnectionsPerIp: 500;
+  maxMessagesPerSecond: 200;
+  maxPayloadSize: 131072
+};
+  loadManagement: {
+  maxConnections: 100000;
+  backpressureThreshold: 5000;
+  messageQueueSize: 50000;
+  gracefulShutdownTimeout: 60000
+};
+  autoScaling: {
+  min: 4;
+  max: 50;
+  targetCPU: 60
+}
+}
+};
+  /**
+     * Chat application preset
+     */
+  chat: {
+  enabled: true;
+  mode: 'server';
+  server: {
+  driver: 'bun';
+  redis: {
+  enabled: true
+};
+  rateLimit: {
+  enabled: true;
+  maxConnectionsPerIp: 10;
+  maxMessagesPerSecond: 20
+};
+  loadManagement: {
+  maxConnections: 50000
+}
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: {
+  enabled: true;
+  maxMembersPerChannel: 500;
+  memberInfoTtl: 60
+}
+}
+};
+  /**
+     * Gaming preset - low latency, high throughput
+     */
+  gaming: {
+  enabled: true;
+  mode: 'server';
+  server: {
+  driver: 'bun';
+  redis: {
+  enabled: true;
+  cluster: true
+};
+  rateLimit: {
+  enabled: true;
+  maxConnectionsPerIp: 50;
+  maxMessagesPerSecond: 100
+};
+  loadManagement: {
+  maxConnections: 50000;
+  backpressureThreshold: 2000;
+  messageQueueSize: 20000
+};
+  autoScaling: {
+  min: 2;
+  max: 20;
+  targetCPU: 50
+}
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: true
+}
+}
+};
+  /**
+   * Serverless mode presets (API Gateway WebSocket)
+   */
+  serverless: {
+  /**
+     * Development preset
+     */
+  development: {
+  enabled: true;
+  mode: 'serverless';
+  debug: true;
+  serverless: {
+  connectionTimeout: 3600;
+  idleTimeout: 600;
+  stageName: 'dev';
+  memorySize: 256;
+  timeout: 30
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: true
+}
+};
+  /**
+     * Production preset
+     */
+  production: {
+  enabled: true;
+  mode: 'serverless';
+  debug: false;
+  serverless: {
+  connectionTimeout: 3600;
+  idleTimeout: 600;
+  stageName: 'production';
+  memorySize: 512;
+  timeout: 30;
+  provisionedConcurrency: 2
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: true
+}
+};
+  /**
+     * Notifications preset - simple push notifications
+     */
+  notifications: {
+  enabled: true;
+  mode: 'serverless';
+  serverless: {
+  connectionTimeout: 7200;
+  idleTimeout: 1800;
+  memorySize: 256;
+  timeout: 15
+};
+  channels: {
+  public: true;
+  private: true;
+  presence: false
+}
+}
+}
+};
+/**
+ * Redis adapter configuration for horizontal scaling
+ */
+export declare interface RealtimeRedisConfig {
+  enabled?: boolean
+  host?: string
+  port?: number
+  password?: string
+  prefix?: string
+  cluster?: boolean
+  sentinels?: Array<{ host: string, port: number }>
+  sentinelName?: string
+}
+/**
+ * Rate limiting configuration
+ */
+export declare interface RealtimeRateLimitConfig {
+  enabled?: boolean
+  maxConnectionsPerIp?: number
+  maxMessagesPerSecond?: number
+  maxPayloadSize?: number
+  banDuration?: number
+}
+/**
+ * Encryption configuration
+ */
+export declare interface RealtimeEncryptionConfig {
+  enabled?: boolean
+  algorithm?: 'aes-256-gcm' | 'chacha20-poly1305'
+  keyRotationInterval?: number
+}
+/**
+ * Webhook configuration
+ */
+export declare interface RealtimeWebhooksConfig {
+  enabled?: boolean
+  url?: string
+  events?: Array<'connection' | 'disconnection' | 'subscription' | 'message' | 'error'>
+  headers?: Record<string, string>
+  timeout?: number
+  retries?: number
+}
+/**
+ * Queue integration configuration
+ */
+export declare interface RealtimeQueueConfig {
+  enabled?: boolean
+  driver?: 'redis' | 'sqs' | 'memory'
+  batchSize?: number
+  flushInterval?: number
+}
+/**
+ * Load management configuration
+ */
+export declare interface RealtimeLoadConfig {
+  maxConnections?: number
+  backpressureThreshold?: number
+  messageQueueSize?: number
+  gracefulShutdownTimeout?: number
+}
+/**
+ * Presence channel configuration
+ */
+export declare interface RealtimePresenceConfig {
+  enabled?: boolean
+  maxMembersPerChannel?: number
+  memberInfoTtl?: number
+}
+/**
+ * Server mode configuration (ts-broadcasting)
+ */
+export declare interface RealtimeServerConfig {
+  host?: string
+  port?: number
+  scheme?: 'ws' | 'wss'
+  driver?: 'bun' | 'reverb' | 'pusher' | 'ably'
+  redis?: RealtimeRedisConfig
+  rateLimit?: RealtimeRateLimitConfig
+  encryption?: RealtimeEncryptionConfig
+  webhooks?: RealtimeWebhooksConfig
+  queue?: RealtimeQueueConfig
+  loadManagement?: RealtimeLoadConfig
+  instances?: number
+  autoScaling?: {
+    min?: number
+    max?: number
+    targetCPU?: number
+    targetMemory?: number
+  }
+  healthCheck?: {
+    enabled?: boolean
+    path?: string
+    interval?: number
+  }
+  metrics?: {
+    enabled?: boolean
+    port?: number
+    path?: string
+  }
+  tls?: {
+    enabled?: boolean
+    cert?: string
+    key?: string
+  }
+}
+/**
+ * Serverless mode configuration
+ */
+export declare interface RealtimeServerlessConfig {
+  connectionTimeout?: number
+  idleTimeout?: number
+  stageName?: string
+  memorySize?: number
+  timeout?: number
+  provisionedConcurrency?: number
+}
+/**
+ * Channel configuration
+ */
+export declare interface RealtimeChannelsConfig {
+  public?: boolean
+  private?: boolean
+  presence?: boolean | RealtimePresenceConfig
+}
+export declare interface RealtimeOptions {
+  enabled?: boolean
+  mode?: RealtimeMode
+  driver?: 'socket' | 'pusher' | 'bun' | 'reverb' | 'ably'
+  server?: RealtimeServerConfig
+  serverless?: RealtimeServerlessConfig
+  channels?: RealtimeChannelsConfig
+  socket?: {
+    port?: number
+    host?: string
+    cors?: {
+      origin: string | string[]
+      methods: string[]
+    }
+  }
+  pusher?: {
+    appId: string
+    key: string
+    secret: string
+    cluster?: string
+    useTLS?: boolean
+  }
+  app?: {
+    id?: string
+    key?: string
+    secret?: string
+  }
+  domain?: string
+  debug?: boolean
+}
+export declare interface RealtimeInstance {
+  event: string
+  handle?: (data?: any) => Promise<{ channel: string, type: 'public' | 'private' | 'presence' } | void>
+}
+export declare interface RealtimeDriver {
+  connect: () => Promise<void>
+  disconnect: () => Promise<void>
+  subscribe: (channel: string, callback: (data: any) => void) => void
+  unsubscribe: (channel: string) => void
+  publish: (channel: string, data: any) => void
+  broadcast: (channel: string, event: string, data?: any, type?: ChannelType) => void
+  isConnected: () => boolean
+}
+export declare interface Broadcastable {
+  broadcastEvent: () => Promise<void>
+  broadcastEventNow: () => Promise<void>
+  setChannel: (channel: string) => this
+  excludeCurrentUser: () => this
+  setPresenceChannel: () => this
+  setPrivateChannel: () => this
+}
+export declare interface BroadcastInstance {
+  channel?: string
+  event?: string
+  handle?: (data: any) => Promise<void>
+}
+/**
+ * Options for the emit function
+ */
+export declare interface EmitOptions {
+  private?: boolean
+  presence?: boolean
+  exclude?: string | string[]
+  driver?: DriverType
+}
+/**
+ * Realtime deployment mode
+ * - 'serverless': Uses API Gateway WebSocket + Lambda + DynamoDB
+ * - 'server': Uses ts-broadcasting Bun WebSocket server (ECS/Fargate)
+ */
+export type RealtimeMode = 'serverless' | 'server';
+export type RealtimeConfig = Partial<RealtimeOptions>;
+export type DriverType = 'socket' | 'pusher' | 'bun' | 'reverb' | 'ably';
+export type ChannelType = 'public' | 'private' | 'presence';

package/dist/request.d.ts

@@ -0,0 +1,265 @@
+import { User } from '@stacksjs/orm';
+import type { AuthToken } from '@stacksjs/types';
+import type { Infer } from '@stacksjs/ts-validation';
+import type { UploadedFile } from '@stacksjs/storage';
+declare interface RequestData {
+  [key: string]: any
+}
+/**
+ * Cookie-access helper exposed via `request.cookies` on
+ * {@link RequestInstance}. The methods mirror bun-router's
+ * `CookieAccessor` — duplicated locally so this package doesn't
+ * have to depend on bun-router for a single type. Keep the surface
+ * in sync if bun-router extends its accessor.
+ */
+export declare interface RequestCookies {
+  get: (name: string) => string | undefined
+  set: (name: string, value: string, options?: {
+    path?: string
+    domain?: string
+    secure?: boolean
+    httpOnly?: boolean
+    sameSite?: 'strict' | 'lax' | 'none'
+    maxAge?: number
+    expires?: Date
+  }) => void
+  delete: (name: string, options?: { path?: string, domain?: string }) => void
+  getAll: () => Record<string, string>
+}
+/**
+ * Collection interface for array data (Laravel-style)
+ */
+export declare interface Collection<T> {
+  items: T[]
+  count: () => number
+  first: () => T | undefined
+  last: () => T | undefined
+  map: <U>(fn: (item: T, index: number) => U) => Collection<U>
+  filter: (fn: (item: T, index: number) => boolean) => Collection<T>
+  find: (fn: (item: T, index: number) => boolean) => T | undefined
+  reduce: <U>(fn: (acc: U, item: T, index: number) => U, initial: U) => U
+  forEach: (fn: (item: T, index: number) => void) => void
+  toArray: () => T[]
+  isEmpty: () => boolean
+  isNotEmpty: () => boolean
+  pluck: <K extends keyof T>(key: K) => Collection<T[K]>
+  unique: () => Collection<T>
+  sortBy: <K extends keyof T>(key: K, direction?: 'asc' | 'desc') => Collection<T>
+  groupBy: <K extends keyof T>(key: K) => Map<T[K], Collection<T>>
+  chunk: (size: number) => Collection<Collection<T>>
+  take: (count: number) => Collection<T>
+  skip: (count: number) => Collection<T>
+  reverse: () => Collection<T>
+  sum: (key?: keyof T) => number
+  avg: (key?: keyof T) => number
+  min: (key?: keyof T) => T | undefined
+  max: (key?: keyof T) => T | undefined
+}
+/**
+ * Safe validated data wrapper (Laravel-style)
+ */
+export declare interface SafeData<T extends Record<string, any> = Record<string, any>> {
+  only: <K extends keyof T>(keys: K[]) => Pick<T, K>
+  except: <K extends keyof T>(keys: K[]) => Omit<T, K>
+  merge: <U extends Record<string, unknown>>(data: U) => T & U
+  all: () => T
+  has: (key: keyof T) => boolean
+  get: <K extends keyof T>(key: K) => T[K]
+}
+export declare interface RequestInstance<TFields extends Record<string, any> = Record<string, any>, TParams extends Record<string, string> = Record<string, string>,> {
+  url: string
+  method: string
+  headers: Headers
+  query: RequestData
+  params: TParams
+  jsonBody?: any
+  formBody?: any
+  files: Record<string, File | File[]>
+  cookies?: RequestCookies
+  get<K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]): TFields[K]
+  get<T = any>(key: string, defaultValue?: T): T
+  input<K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]): TFields[K]
+  input<T = any>(key: string, defaultValue?: T): T
+  all: () => TFields
+  only: <K extends keyof TFields & string>(keys: K[]) => Pick<TFields, K>
+  except: <K extends keyof TFields & string>(keys: K[]) => Omit<TFields, K>
+  has: (key: string | string[]) => boolean
+  hasAny: (keys: string[]) => boolean
+  filled: (key: string | string[]) => boolean
+  missing: (key: string | string[]) => boolean
+  merge: (data: Partial<TFields>) => void
+  keys: () => (keyof TFields & string)[]
+  string: (key: keyof TFields & string, defaultValue?: string) => string
+  integer: (key: keyof TFields & string, defaultValue?: number) => number
+  float: (key: keyof TFields & string, defaultValue?: number) => number
+  boolean: (key: keyof TFields & string, defaultValue?: boolean) => boolean
+  array: <T = unknown>(key: keyof TFields & string) => T[]
+  date: (key: keyof TFields & string, format?: string) => Date | null
+  enum: <T extends Record<string, string | number>>(key: keyof TFields & string, enumType: T) => T[keyof T] | null
+  collect: <T = unknown>(key: keyof TFields & string) => Collection<T>
+  validate: (rules?: RequestValidationRules, messages?: Record<string, string>) => Promise<TFields>
+  getValidated: () => TFields
+  safe: () => SafeData<TFields>
+  whenHas: <T>(key: keyof TFields & string, callback: (value: T) => void, defaultCallback?: () => void) => void
+  whenFilled: <T>(key: keyof TFields & string, callback: (value: T) => void, defaultCallback?: () => void) => void
+  isValue: (key: keyof TFields & string, value: unknown) => boolean
+  file: (key: string) => UploadedFile | null
+  getFiles: (key: string) => UploadedFile[]
+  hasFile: (key: string) => boolean
+  allFiles: () => Record<string, UploadedFile | UploadedFile[]>
+  header: (key: string) => string | null
+  bearerToken: () => string | null | AuthToken
+  param: <K extends keyof TParams | string, D = string>(
+    key: K,
+    defaultValue?: D,
+  ) => K extends keyof TParams ? TParams[K] : (string | D)
+  getParam: <K extends string>(key: K) => K extends NumericField ? number : string
+  route: (key: string) => number | string | null
+  getParams: () => TParams
+  getParamAsInt: (key: string) => number | null
+  old: <T = unknown>(key: keyof TFields & string, defaultValue?: T) => T
+  flashInput: (keys?: (keyof TFields & string)[]) => void
+  flashInputOnly: (keys: (keyof TFields & string)[]) => void
+  flashInputExcept: (keys: (keyof TFields & string)[]) => void
+  json: <T = any>() => Promise<T>
+  isEmpty: () => boolean
+  browser: () => string | null
+  ip: () => string | null
+  ipForRateLimit: () => string | null
+  getMethod: () => HttpMethod
+  user: () => Promise<UserJsonResponse | undefined>
+}
+// Trait methods are attached dynamically by the Stacks model proxy. The
+// open member bag reflects application-level traits that the framework's
+// default User definition cannot know about ahead of time.
+declare type UserJsonResponse = NonNullable<Awaited<ReturnType<typeof User.find>>> & Record<string, any>;
+/**
+ * Loose route-param shape kept around for back-compat with code that
+ * predates {@link RequestInstance}'s `TParams` generic. New code should
+ * rely on the path-extracted `TParams` instead — see {@link ExtractParams}.
+ *
+ * @deprecated Use {@link ExtractParams}-driven typing on the action /
+ *   route signature instead. URL route params are always strings at
+ *   runtime; the `string | number` here misled callers into thinking
+ *   the framework coerced numbers automatically (it doesn't —
+ *   `Number(request.params.id)` is the correct pattern).
+ */
+declare type RouteParams = { [key: string]: string | number } | null;
+/**
+ * Legacy hard-coded list of param names treated as `number` by
+ * {@link RequestInstance.getParam}. The name-match heuristic is
+ * brittle (`'judgeId'`, `'user_id'`, etc. all silently fall through
+ * to `string`) and will be retired in a future release.
+ *
+ * @deprecated The name-match returns `number` for these specific keys
+ *   only — pass the value through {@link Number} or
+ *   {@link RequestInstance.getParamAsInt} for explicit, predictable
+ *   coercion. See stacksjs/stacks#1851 Phase 3.
+ */
+declare type NumericField = 'id' | 'age' | 'count' | 'quantity' | 'amount' | 'price' | 'total' | 'score' | 'rating' | 'duration' | 'size' | 'weight' | 'height' | 'width' | 'length' | 'distance' | 'speed' | 'temperature' | 'volume' | 'capacity' | 'density' | 'pressure' | 'force' | 'energy' | 'power' | 'frequency' | 'voltage' | 'current' | 'resistance' | 'time' | 'date' | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond';
+/**
+ * Template-literal helper that extracts named route params from a
+ * path string (stacksjs/stacks#1851 Phase 2a). Supports both Stacks's
+ * brace-style (`/users/{id}`) and Express-style (`/users/:id`) so a
+ * project using either gets typed `params` out of the box.
+ *
+ * @example
+ *   ExtractParams<'/api/judges/{id}/follow'>  // { id: string }
+ *   ExtractParams<'/api/orders/:orderId/items/:itemId'>  // { orderId: string, itemId: string }
+ *   ExtractParams<'/api/health'>  // Record<string, never>
+ */
+// Step 1: pull the next param name out of either `{name}` or `:name`,
+// recurse on the rest, and union the keys.
+declare type ExtractParamKeys<S extends string> = S extends `${string}{${infer Key}}${infer Rest}`
+    ? Key | ExtractParamKeys<Rest>
+    // colon form: `…/:name/…` (colon must be at a segment boundary
+    // so we don't match `:` inside e.g. a port number; the `/` before
+    // it enforces that)
+    : S extends `${string}/:${infer Key}/${infer Rest}`
+      ? KeyHead<Key> | ExtractParamKeys<`/${Rest}`>
+      // tail colon-form: `…/:name` (no trailing slash)
+      : S extends `${string}/:${infer Key}`
+        ? KeyHead<Key>
+        : never;
+// `KeyHead<'name>'>` → `'name>'` because TS template literal infers
+// the longest possible match. We need to handle params that are at
+// the end of the path AND followed by a query string. This util
+// truncates a captured key at the first non-name character.
+declare type KeyHead<S extends string> = S extends `${infer H}/${string}` ? H :
+    S extends `${infer H}?${string}` ? H :
+      S extends `${infer H}.${string}` ? H :
+        S;
+export type ExtractParams<S extends string> = [ExtractParamKeys<S>] extends [never]
+    ? Record<string, never>
+    : { [K in ExtractParamKeys<S>]: string }
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';
+/**
+ * RequestInstance - Generic, model-aware request interface with Laravel-style methods.
+ *
+ * When used bare (`RequestInstance`), all methods accept any string keys (backward compatible).
+ * When parameterized with model fields (`RequestInstance<{ title: string, views: number }>`),
+ * all input methods narrow to those fields with full autocomplete and type inference.
+ *
+ * The global type alias connects this to models:
+ *   `RequestInstance<typeof Post>` → narrows to Post's fields automatically.
+ *
+ * @example
+ * // Untyped (accepts any key)
+ * function handle(request: RequestInstance) {
+ *   request.get('anything') // returns any
+ * }
+ *
+ * @example
+ * // Model-aware (narrows to Post's fields)
+ * function handle(request: RequestInstance<typeof Post>) {
+ *   request.get('title')   // autocompletes, returns string
+ *   request.get('views')   // autocompletes, returns number
+ *   request.get('invalid') // TS error!
+ *   const data = await request.validate() // returns typed Post fields
+ * }
+ */
+/**
+ * Public alias for `RequestInstance<TFields>`. Use this in actions when
+ * you want to type the `request` argument explicitly (e.g. without
+ * pulling in a model object).
+ *
+ * @example
+ * ```ts
+ * import { Action } from '@stacksjs/actions'
+ * import type { ActionRequest } from '@stacksjs/types'
+ *
+ * type CreatePostInput = { title: string; body: string }
+ *
+ * export default new Action({
+ *   name: 'CreatePost',
+ *   handle(request: ActionRequest<CreatePostInput>) {
+ *     const { title, body } = request.only(['title', 'body'])
+ *     // ^ inferred as { title: string; body: string }
+ *   },
+ * })
+ * ```
+ */
+export type ActionRequest<TFields extends Record<string, any> = Record<string, any>, TParams extends Record<string, string> = Record<string, string>,> = RequestInstance<TFields, TParams>;
+/**
+ * Read the body shape declared by an action's `validations:` field as
+ * a TypeScript object type (stacksjs/stacks#1851 Phase 2b). Threaded
+ * into {@link RequestInstance}'s `TFields` so `request.all()` returns
+ * the body shape with the field types {@link Infer}'d from each
+ * `schema.X()` rule.
+ *
+ * @example
+ *   const validations = {
+ *     email:    { rule: schema.string().email() },
+ *     password: { rule: schema.string().min(8) },
+ *     remember: { rule: schema.boolean() },
+ *   } as const
+ *   type Body = InferValidations<typeof validations>
+ *   // → { email: string, password: string, remember: boolean }
+ */
+export type InferValidations<V extends Record<string, { rule: any }>> = {
+  [K in keyof V]: Infer<V[K]['rule']>
+}
+export type RequestValidationRules = Record<string, string | {
+  rule: { validate: (value: any) => any }
+  message?: string | Record<string, string>
+}>;