@stacksjs/types 0.70.22 → 0.70.25

package/src/request.ts

@@ -1,49 +1,371 @@
-import type { VineType } from '@stacksjs/types'
+import type { ModelRow } from '@stacksjs/orm'
+import { User } from '@stacksjs/orm'
+import type { UploadedFile } from '@stacksjs/storage'
+import type { AuthToken, RouteParam } from '@stacksjs/types'
+
+type UserJsonResponse = ModelRow<typeof User>
 
-export type * from '../../../types/requests'
 interface RequestData {
   [key: string]: any
 }
 
 type RouteParams = { [key: string]: string | number } | null
 
-interface ValidationField {
-  rule: VineType
-  message: Record<string, string>
+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'
+
+/**
+ * Collection interface for array data (Laravel-style)
+ */
+export 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
 }
 
-interface CustomAttributes {
-  [key: string]: ValidationField
+/**
+ * Safe validated data wrapper (Laravel-style)
+ */
+export 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 interface RequestInstance {
-  addQuery: (url: URL) => void
+/**
+ * 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>
 
-  addBodies: (params: any) => void
+export interface RequestInstance<TFields extends Record<string, any> = Record<string, any>> {
+  // ==========================================================================
+  // Native Request properties
+  // ==========================================================================
 
-  addParam: (param: RouteParams) => void
+  url: string
+  method: string
+  headers: Headers
 
-  get: <T>(element: string, defaultValue?: T) => T
+  // Raw data access (always untyped — use get()/input() for typed access)
+  query: RequestData
+  params: RouteParams
+  jsonBody?: any
+  formBody?: any
+  files: Record<string, File | File[]>
 
-  header: (element: string) => string | number | boolean | null
+  // ==========================================================================
+  // Model-aware Input Methods
+  //
+  // Keys narrow to `keyof TFields` when a model type is provided.
+  // Return types narrow to the field's actual type.
+  // ==========================================================================
 
-  Header: (element: string) => string | number | boolean | null
+  /**
+   * Get input value from any source (query, body, params)
+   * @example request.get('title')           // returns string (when model-aware)
+   * @example request.get('views', 0)        // returns number with default
+   */
+  get: <K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]) => TFields[K]
 
-  all: () => RequestData
+  /**
+   * Alias for get() - Laravel compatibility
+   */
+  input: <K extends keyof TFields & string>(key: K, defaultValue?: TFields[K]) => TFields[K]
 
-  validate: (attributes: CustomAttributes) => void
+  /**
+   * Get all input data (typed to model fields when model-aware)
+   */
+  all: () => TFields
 
-  has: (element: string) => boolean
+  /**
+   * Get only specified keys — returns a precisely picked type
+   * @example request.only(['title', 'views']) // { title: string, views: number }
+   */
+  only: <K extends keyof TFields & string>(keys: K[]) => Pick<TFields, K>
 
-  isEmpty: () => boolean
+  /**
+   * Get all except specified keys — returns a precisely omitted type
+   * @example request.except(['id', 'created_at']) // omits those fields
+   */
+  except: <K extends keyof TFields & string>(keys: K[]) => Omit<TFields, K>
 
-  extractParamsFromRoute: (routePattern: string, pathname: string) => void
+  /**
+   * Check if input has a key (or all keys if array) — keys narrowed to model fields
+   * @example request.has('title')
+   * @example request.has(['title', 'views'])
+   */
+  has: (key: (keyof TFields & string) | (keyof TFields & string)[]) => boolean
 
-  getParam: (key: string) => number | string | null
+  /**
+   * Check if input has any of the specified keys
+   * @example request.hasAny(['title', 'views'])
+   */
+  hasAny: (keys: (keyof TFields & string)[]) => boolean
 
-  route: (key: string) => number | string | null
+  /**
+   * Check if input is filled (present and not empty)
+   * @example request.filled('title')
+   */
+  filled: (key: (keyof TFields & string) | (keyof TFields & string)[]) => boolean
 
-  getParams: () => RouteParams
+  /**
+   * Check if input is missing
+   * @example request.missing('title')
+   */
+  missing: (key: (keyof TFields & string) | (keyof TFields & string)[]) => boolean
+
+  /**
+   * Merge additional data into input — accepts partial model fields
+   */
+  merge: (data: Partial<TFields>) => void
+
+  /**
+   * Get all input keys — returns model field names when model-aware
+   */
+  keys: () => (keyof TFields & string)[]
+
+  // ==========================================================================
+  // Type-casting Methods — keys narrowed to model fields
+  // ==========================================================================
+
+  /**
+   * Get string input
+   * @example request.string('title')
+   */
+  string: (key: keyof TFields & string, defaultValue?: string) => string
+
+  /**
+   * Get integer input
+   * @example request.integer('views', 0)
+   */
+  integer: (key: keyof TFields & string, defaultValue?: number) => number
+
+  /**
+   * Get float input
+   * @example request.float('price', 0.0)
+   */
+  float: (key: keyof TFields & string, defaultValue?: number) => number
+
+  /**
+   * Get boolean input
+   * @example request.boolean('is_active', false)
+   */
+  boolean: (key: keyof TFields & string, defaultValue?: boolean) => boolean
+
+  /**
+   * Get input as array
+   * @example request.array('tags')
+   */
+  array: <T = unknown>(key: keyof TFields & string) => T[]
+
+  /**
+   * Parse date input
+   * @example request.date('published_at')
+   */
+  date: (key: keyof TFields & string, format?: string) => Date | null
+
+  /**
+   * Parse enum input
+   * @example request.enum('status', StatusEnum)
+   */
+  enum: <T extends Record<string, string | number>>(key: keyof TFields & string, enumType: T) => T[keyof T] | null
+
+  /**
+   * Get input as collection
+   * @example request.collect('items')
+   */
+  collect: <T = unknown>(key: keyof TFields & string) => Collection<T>
+
+  // ==========================================================================
+  // Validation Methods — returns typed model fields when model-aware
+  // ==========================================================================
+
+  /**
+   * Validate the request data.
+   * When model-aware, rules are optional (uses model's attribute validation).
+   * Returns the validated data typed to model fields.
+   *
+   * @example await request.validate()                    // uses model rules
+   * @example await request.validate({ name: 'required' }) // custom rules
+   */
+  validate: (rules?: Record<string, string>, messages?: Record<string, string>) => Promise<TFields>
+
+  /**
+   * Get previously validated data, typed to model fields
+   */
+  getValidated: () => TFields
+
+  /**
+   * Get safe validated data wrapper with typed access
+   * @example request.safe().only(['title', 'views']) // Pick<TFields, 'title' | 'views'>
+   * @example request.safe().get('title')              // string
+   */
+  safe: () => SafeData<TFields>
 
+  // ==========================================================================
+  // Conditional Methods — keys narrowed to model fields
+  // ==========================================================================
+
+  /**
+   * Execute callback when input has a value
+   * @example request.whenHas('title', (value) => console.log(value))
+   */
+  whenHas: <T>(key: keyof TFields & string, callback: (value: T) => void, defaultCallback?: () => void) => void
+
+  /**
+   * Execute callback when input is filled
+   * @example request.whenFilled('title', (value) => console.log(value))
+   */
+  whenFilled: <T>(key: keyof TFields & string, callback: (value: T) => void, defaultCallback?: () => void) => void
+
+  /**
+   * Check if input matches a value
+   */
+  isValue: (key: keyof TFields & string, value: unknown) => boolean
+
+  // ==========================================================================
+  // File Methods — not narrowed to model fields (files are independent)
+  // ==========================================================================
+
+  /**
+   * Get an uploaded file by key
+   * @example const avatar = request.file('avatar')
+   * @example await avatar?.store('avatars')
+   */
+  file: (key: string) => UploadedFile | null
+
+  /**
+   * Get all uploaded files for a key (for multiple file inputs)
+   */
+  getFiles: (key: string) => UploadedFile[]
+
+  /**
+   * Check if a file was uploaded
+   */
+  hasFile: (key: string) => boolean
+
+  /**
+   * Get all uploaded files
+   */
+  allFiles: () => Record<string, UploadedFile | UploadedFile[]>
+
+  // ==========================================================================
+  // Header Methods
+  // ==========================================================================
+
+  header: (key: string) => string | null
+  bearerToken: () => string | null | AuthToken
+
+  // ==========================================================================
+  // Route & Param Methods — not narrowed to model fields
+  // ==========================================================================
+
+  getParam: <K extends string>(key: K) => K extends NumericField ? number : string
+  route: (key: string) => number | string | null
+  getParams: () => RouteParams
   getParamAsInt: (key: string) => number | null
+
+  // ==========================================================================
+  // Session/Flash Methods — keys narrowed to model fields
+  // ==========================================================================
+
+  /**
+   * Get old input (for form repopulation)
+   */
+  old: <T = unknown>(key: keyof TFields & string, defaultValue?: T) => T
+
+  /**
+   * Flash input to session for form repopulation
+   */
+  flashInput: (keys?: (keyof TFields & string)[]) => void
+
+  /**
+   * Flash only specific keys
+   */
+  flashInputOnly: (keys: (keyof TFields & string)[]) => void
+
+  /**
+   * Flash except specific keys
+   */
+  flashInputExcept: (keys: (keyof TFields & string)[]) => void
+
+  // ==========================================================================
+  // Utility Methods
+  // ==========================================================================
+
+  json: <T = any>() => Promise<T>
+  isEmpty: () => boolean
+  browser: () => string | null
+  ip: () => string | null
+  ipForRateLimit: () => string | null
+  getMethod: () => HttpMethod
+  user: () => Promise<UserJsonResponse | undefined>
 }

package/src/router.ts

@@ -1,10 +1,30 @@
 import type { Action } from '@stacksjs/actions'
+type Request = any
+import type { ValidationType } from '@stacksjs/ts-validation'
+import type { HttpMethod } from './request'
 
 type ActionPath = string
 // need to refactor before, after, view to be a part of some other type
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'before' | 'after' | 'view'
+export type RouteCallback = ((_params?: Record<string, any>) => any | string | object) | ((req: any, res: any) => Promise<void>)
 
-export type RouteCallback = (params?: Record<string, any>) => any | string | object
+export interface RequestData {
+  [key: string]: any
+}
+
+export interface ValidationField {
+  rule: ValidationType
+  message: Record<string, string>
+}
+
+export type RouterAuthToken = `${number}:${number}:${string}`
+
+export interface CustomAttributes {
+  [key: string]: ValidationField
+}
+
+export interface RouteParams { [key: string]: string | number }
+
+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 interface Route {
   name: string
@@ -20,19 +40,30 @@ export interface Route {
   statusCode?: StatusCode
 }
 
+export interface ServeOptions {
+  host?: string
+  port?: number
+  debug?: boolean
+  timezone?: string
+}
+
+export interface Options {
+  statusCode?: StatusCode
+}
+
 export interface MiddlewareOptions {
   name: string
   description?: string
   priority: number
-  handle: () => Promise<void>
+  handle: (request: Request) => Promise<void> | void
 }
 
 export type StatusCode = 200 | 201 | 202 | 204 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 500
 export type RedirectCode = Extract<StatusCode, 301 | 302>
 
-export type RouteParam = { [key: string]: string | number } | null
+export interface RouteParam { [key: string]: string | number }
 
-export type MiddlewareFn = () => void
+export type MiddlewareFn = (_request: Request) => Promise<void>
 
 export interface Middlewares {
   logger: MiddlewareFn
@@ -64,3 +95,30 @@ export interface RouterInterface {
   middleware: (middleware: Route['middleware']) => this
   getRoutes: () => Promise<Route[]>
 }
+
+export 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
+}

package/src/search-engine.ts

@@ -37,16 +37,10 @@ export interface SearchEngineOptions {
    *
    * The search engine to utilize.
    *
-   * @default string 'opensearch'
-   * @see https://stacksjs.org/docs/search-engine
+   * @default string 'meilisearch'
+   * @see https://stacksjs.com/docs/search-engine
    */
-  driver: 'opensearch'
-  // driver: 'meilisearch' | 'algolia' | 'typesense' | 'opensearch' wip
-
-  // meilisearch?: {
-  //   host: string
-  //   apiKey: string
-  // }
+  driver: 'meilisearch' | 'algolia' | 'opensearch'
 
   opensearch?: {
     host: string
@@ -57,10 +51,16 @@ export interface SearchEngineOptions {
 
   meilisearch?: {
     host: string
-    protocol: number
-    port: number
-    auth: string
+    protocol?: number
+    port?: number
+    auth?: string
+    apiKey: string
+  }
+
+  algolia?: {
+    appId: string
     apiKey: string
+    searchOnlyApiKey?: string
   }
 
   filters?: {
@@ -79,6 +79,7 @@ export type SearchEngineConfig = Partial<SearchEngineOptions>
 
 export interface SearchEngineDriver {
   client: () => MeiliSearch
+  resetClient?: () => void
 
   search: (index: string, params: any) => Promise<SearchResponse<Record<string, any>>>
 
@@ -116,7 +117,6 @@ export interface SearchEngineDriver {
   getSettings: (index: string) => Promise<Settings>
   updateSettings: (index: string, settings: Settings) => Promise<EnqueuedTask>
   resetSettings: (index: string) => Promise<EnqueuedTask>
-  å
   getPagination: (index: string) => Promise<PaginationSettings>
   updatePagination: (index: string, pagination: PaginationSettings) => Promise<EnqueuedTask>
   resetPagination: (index: string) => Promise<EnqueuedTask>

package/src/services.ts

@@ -11,6 +11,34 @@ export interface ServicesOptions {
     region: string
   }
 
+  github?: {
+    clientId: string
+    clientSecret: string
+    redirectUrl: string
+    scopes?: string[]
+  }
+
+  google?: {
+    clientId: string
+    clientSecret: string
+    redirectUrl: string
+    scopes?: string[]
+  }
+
+  facebook?: {
+    clientId: string
+    clientSecret: string
+    redirectUrl: string
+    scopes?: string[]
+  }
+
+  twitter?: {
+    clientId: string
+    clientSecret: string
+    redirectUrl: string
+    scopes?: string[]
+  }
+
   godaddy?: {
     apiKey: string
     apiSecret: string
@@ -68,17 +96,84 @@ export interface ServicesOptions {
     retryTimeout?: number
   }
 
+  /**
+   * SMTP Configuration for local development
+   * Works with HELO, Mailtrap Desktop, Mailhog, etc.
+   */
+  smtp?: {
+    host: string
+    port: number
+    username?: string
+    password?: string
+    encryption?: 'tls' | 'ssl' | null
+    maxRetries?: number
+    retryTimeout?: number
+  }
+
   slack?: {
-    appId: string
-    clientId: string
-    secretKey: string
+    appId?: string
+    clientId?: string
+    secretKey?: string
+    webhookUrl?: string
+    botToken?: string
     maxRetries?: number
     retryTimeout?: number
   }
 
+  discord?: {
+    webhookUrl?: string
+    botToken?: string
+    maxRetries?: number
+    retryTimeout?: number
+  }
+
+  teams?: {
+    webhookUrl?: string
+    maxRetries?: number
+    retryTimeout?: number
+  }
+
+  // Push Notification Services
+  expo?: {
+    accessToken?: string
+  }
+
+  fcm?: {
+    serverKey?: string
+    projectId?: string
+    clientEmail?: string
+    privateKey?: string
+  }
+
+  // AI Services
+  openai?: {
+    apiKey?: string
+    model?: string
+    embeddingModel?: string
+    baseUrl?: string
+  }
+
+  anthropic?: {
+    apiKey?: string
+    model?: string
+    maxTokens?: number
+  }
+
+  ollama?: {
+    host?: string
+    model?: string
+    embeddingModel?: string
+  }
+
   stripe?: {
-    appId: string
-    apiKey: string
+    secretKey?: string
+    publicKey?: string
+    /**
+     * Pinned Stripe API version. Defaults to whatever the bundled SDK
+     * was compiled against; override here when rolling forward without
+     * a code change. Format: 'YYYY-MM-DD' or 'YYYY-MM-DD.preview'.
+     */
+    apiVersion?: string
   }
 
   // supabase?: {