@stacksjs/types 0.70.23 → 0.70.25

package/dist/src/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/src/request.d.ts

@@ -0,0 +1,154 @@
+import { User } from '@stacksjs/orm';
+import type { AuthToken } from '@stacksjs/types';
+import type { ModelRow } from '@stacksjs/orm';
+import type { UploadedFile } from '@stacksjs/storage';
+declare interface RequestData {
+  [key: string]: any
+}
+/**
+ * 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>> {
+  url: string
+  method: string
+  headers: Headers
+  query: RequestData
+  params: RouteParams
+  jsonBody?: any
+  formBody?: any
+  files: Record<string, File | File[]>
+  get: <K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]) => TFields[K]
+  input: <K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]) => TFields[K]
+  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: (keyof TFields & string) | (keyof TFields & string)[]) => boolean
+  hasAny: (keys: (keyof TFields & string)[]) => boolean
+  filled: (key: (keyof TFields & string) | (keyof TFields & string)[]) => boolean
+  missing: (key: (keyof TFields & string) | (keyof TFields & 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?: Record<string, string>, 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
+  getParam: <K extends string>(key: K) => K extends NumericField ? number : string
+  route: (key: string) => number | string | null
+  getParams: () => RouteParams
+  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>
+}
+declare type UserJsonResponse = ModelRow<typeof User>;
+declare type RouteParams = { [key: string]: string | number } | null;
+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';
+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>> = RequestInstance<TFields>;

package/dist/{response.d.ts → src/response.d.ts}

@@ -12,4 +12,4 @@ export declare interface ResponseData {
   status: number
   headers: { [key: string]: string }
   body: string
-}
+}

package/dist/src/router.d.ts

@@ -0,0 +1,105 @@
+import type { Action } from '@stacksjs/actions';
+import type { HttpMethod } from './request';
+import type { ValidationType } from '@stacksjs/ts-validation';
+export declare interface RequestData {
+  [key: string]: any
+}
+export declare interface ValidationField {
+  rule: ValidationType
+  message: Record<string, string>
+}
+export declare interface CustomAttributes {
+  [key: string]: ValidationField
+}
+export declare interface RouteParams { [key: string]: string | number }
+export declare interface Route {
+  name: string
+  uri: string
+  url: string
+  path?: string
+  prefix?: string
+  method: HttpMethod
+  pattern: RegExp
+  callback: RouteCallback | ActionPath | Action | Promise<any>
+  paramNames: string[]
+  middleware?: string | string[]
+  statusCode?: StatusCode
+}
+export declare interface ServeOptions {
+  host?: string
+  port?: number
+  debug?: boolean
+  timezone?: string
+}
+export declare interface Options {
+  statusCode?: StatusCode
+}
+export declare interface MiddlewareOptions {
+  name: string
+  description?: string
+  priority: number
+  handle: (request: Request) => Promise<void> | void
+}
+export declare interface RouteParam { [key: string]: string | number }
+export declare interface Middlewares {
+  logger: MiddlewareFn
+  auth: MiddlewareFn
+  [key: string]: MiddlewareFn
+}
+export declare interface RouteGroupOptions {
+  prefix?: string
+  middleware?: Route['middleware']
+}
+export declare interface RouterInterface {
+  get: (url: Route['url'], callback: Route['callback']) => this
+  post: (url: Route['url'], callback: Route['callback']) => this
+  view: (url: Route['url'], callback: Route['callback']) => this
+  redirect: (url: Route['url'], callback: Route['callback'], status?: RedirectCode) => this
+  delete: (url: Route['url'], callback: Route['callback']) => this
+  patch: (url: Route['url'], callback: Route['callback']) => this
+  put: (url: Route['url'], callback: Route['callback']) => this
+  email: (url: Route['url']) => Promise<this>
+  health: () => Promise<this>
+  job: (url: Route['url']) => Promise<this>
+  action: (url: Route['url']) => Promise<this>
+  group: (options: Prefix | RouteGroupOptions, callback: () => void) => this
+  name: (name: string) => this
+  middleware: (middleware: Route['middleware']) => this
+  getRoutes: () => Promise<Route[]>
+}
+export declare interface RouterInstance {
+  query: any
+  params: RouteParams
+  headers: any
+  addQuery: (url: URL) => void
+  addBodies: (params: any) => void
+  addParam: (param: RouteParam) => void
+  addHeaders: (headerParams: Headers) => void
+  get: <K extends string>(element: K, defaultValue?: K extends NumericField ? number : string) => K extends NumericField ? number : string
+  all: () => any
+  validate: (attributes?: CustomAttributes) => Promise<void>
+  has: (element: string) => boolean
+  isEmpty: () => boolean
+  extractParamsFromRoute: (routePattern: string, pathname: string) => void
+  header: (headerParam: string) => string | number | boolean | null
+  getHeaders: () => any
+  Header: (headerParam: string) => string | number | boolean | null
+  getParam: <T>(key: string) => T
+  route: (key: string) => number | string | null
+  bearerToken: () => string | null | RouterAuthToken
+  getParams: () => RouteParams
+  getParamAsInt: (key: string) => number | null
+  browser: () => string | null
+  ip: () => string | null
+  ipForRateLimit: () => string | null
+}
+declare type Request = any;
+declare type ActionPath = string;
+// need to refactor before, after, view to be a part of some other type
+export type RouteCallback = ((_params?: Record<string, any>) => any | string | object) | ((req: any, res: any) => Promise<void>);
+export type RouterAuthToken = `${number}:${number}:${string}`;
+export 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';
+export type StatusCode = 200 | 201 | 202 | 204 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 500;
+export type RedirectCode = Extract<StatusCode, 301 | 302>;
+export type MiddlewareFn = (_request: Request) => Promise<void>;
+declare type Prefix = string;