@stacksjs/types 0.70.23 → 0.70.25

package/src/cache.ts

@@ -1,121 +1,278 @@
-import type { GetOptions } from 'bentocache/types'
-
+/**
+ * Cache Options - Configuration for the caching system
+ */
 export interface CacheOptions {
   /**
    * **Cache Driver**
    *
-   * This value determines the cache driver that will be used by your application to store
-   * cached data. By default, Stacks uses the "redis" driver, which stores cached data in
-   * in a self-configufed Redis instance. You may use any of the other drivers provided
-   * by Stacks or write your own custom driver.
-   *
-   * @default "redis"
-   * @example "redis"
-   * @example "memcached"
-   * @example "dynamodb"
+   * The cache driver that will be used by your application to store
+   * cached data. Supports 'memory' and 'redis' drivers.
    *
-   * @see https://stacks.js.org/docs/cache
+   * @default "memory"
    */
-  driver: string
+  driver: 'memory' | 'redis'
 
   /**
    * **Cache Prefix**
    *
-   * This value determines the prefix that will be used when storing items in the cache. This
-   * prefix may be useful when multiple applications are sharing the same cache driver so that
-   * they may avoid collisions when attempting to retrieve items from the cache.
+   * The prefix used when storing items in the cache. Useful when
+   * multiple applications share the same cache driver.
    *
-   * @default string "stacks"
-   * @example "stacks"
-   *
-   * @see https://stacks.js.org/docs/cache
+   * @default "stacks"
    */
   prefix: string
 
   /**
    * **Cache TTL**
    *
-   * This value determines the default time to live for items stored in the cache. This value
-   * may be overridden when storing items in the cache. If no value is specified, the cache
-   * driver will default to a reasonable time to live for the given item.
+   * Default time to live for items stored in the cache (in seconds).
+   * Use 0 for no expiration.
    *
-   * @default number 3600
-   * @example 3600
-   * @example 3600 * 24
-   * @example -1 (never expires)
+   * @default 3600
    */
   ttl: number
 
+  /**
+   * **Max Keys**
+   *
+   * Maximum number of keys to store in the cache.
+   * Use -1 for unlimited.
+   *
+   * @default -1
+   */
+  maxKeys?: number
+
+  /**
+   * **Use Clones**
+   *
+   * Whether to clone values when getting/setting.
+   * Disable for better performance with immutable data.
+   *
+   * @default true
+   */
+  useClones?: boolean
+
+  /**
+   * **Driver-specific configurations**
+   */
   drivers: {
     redis?: {
-      connection: string
+      /**
+       * Redis connection URL
+       * @example "redis://localhost:6379"
+       */
+      url?: string
 
       /**
-       * **Redis Host**
-       *
-       * This value determines the host that will be used to connect to the Redis server.
-       *
-       * @default string "localhost"
-       * @example "localhost"
+       * Redis Host
+       * @default "localhost"
        */
       host: string
 
       /**
-       * **Redis Port**
-       *
-       * This value determines the port that will be used to connect to the Redis server.
-       *
-       * @default number 6379
-       * @example 6379
+       * Redis Port
+       * @default 6379
        */
       port: number
 
       /**
-       * **Redis Username**
-       *
-       * This value determines the username that will be used to connect to the Redis server.
-       *
-       * @default string ""
-       * @example "admin"
+       * Redis Username
        */
-      username: string
+      username?: string
 
       /**
-       * **Redis Password**
-       *
-       * This value determines the password that will be used to connect to the Redis server.
-       *
-       * @default string ""
-       * @example "password"
+       * Redis Password
        */
-      password: string
+      password?: string
+
+      /**
+       * Redis Database number
+       * @default 0
+       */
+      database?: number
+
+      /**
+       * Enable TLS
+       * @default false
+       */
+      tls?: boolean
     }
 
-    memcached?: object
+    memory?: {
+      /**
+       * Maximum number of keys
+       * @default -1
+       */
+      maxKeys?: number
 
-    dynamodb?: {
-      key: string
-      secret: string
-      region: string
-      table: string
-      endpoint: string
+      /**
+       * Check period for expired keys (in seconds)
+       * @default 600
+       */
+      checkPeriod?: number
+
+      /**
+       * Delete keys on expire
+       * @default true
+       */
+      deleteOnExpire?: boolean
     }
   }
 }
 
 export type CacheConfig = Partial<CacheOptions>
 
+/**
+ * Cache Driver Interface - Defines the API for all cache implementations
+ */
 export interface CacheDriver {
-  set: (key: string, value: string, ttl?: number) => Promise<void>
-  setForever: (key: string, value: string, ttl?: number) => Promise<void>
-  get: <T> (key: GetOptions<T>) => Promise<T>
-  getOrSet: <T> (key: string, value: T) => Promise<T>
-  remove: (key: string) => Promise<void>
+  /**
+   * Get a cached value
+   */
+  get: <T>(key: string) => Promise<T | undefined>
+
+  /**
+   * Get multiple cached values
+   */
+  mget: <T>(keys: string[]) => Promise<Record<string, T>>
+
+  /**
+   * Set a cached value with optional TTL (in seconds)
+   */
+  set: <T>(key: string, value: T, ttl?: number) => Promise<boolean>
+
+  /**
+   * Set multiple cached values
+   */
+  mset: <T>(entries: Array<{ key: string, value: T, ttl?: number }>) => Promise<boolean>
+
+  /**
+   * Set a cached value that never expires
+   */
+  setForever: <T>(key: string, value: T) => Promise<boolean>
+
+  /**
+   * Get a value or set it if not cached
+   */
+  getOrSet: <T>(key: string, fetcher: () => T | Promise<T>, ttl?: number) => Promise<T>
+
+  /**
+   * Delete one or more keys
+   */
+  del: (keys: string | string[]) => Promise<number>
+
+  /**
+   * Check if a key exists
+   */
   has: (key: string) => Promise<boolean>
+
+  /**
+   * Check if a key is missing
+   */
   missing: (key: string) => Promise<boolean>
-  del: (key: string) => Promise<void>
-  deleteMany: (keys: string[]) => Promise<void>
+
+  /**
+   * Delete a single key (alias for del)
+   */
+  remove: (key: string) => Promise<void>
+
+  /**
+   * Delete multiple keys
+   */
+  deleteMany: (keys: string[]) => Promise<number>
+
+  /**
+   * Clear all cached values
+   */
   clear: () => Promise<void>
-  deleteAll: () => Promise<void>
+
+  /**
+   * Clear all cached values (alias for clear)
+   */
+  flush: () => Promise<void>
+
+  /**
+   * Get all keys matching a pattern
+   */
+  keys: (pattern?: string) => Promise<string[]>
+
+  /**
+   * Get the TTL of a key (in seconds)
+   */
+  getTtl: (key: string) => Promise<number | undefined>
+
+  /**
+   * Set/update the TTL of a key
+   */
+  ttl: (key: string, ttl: number) => Promise<boolean>
+
+  /**
+   * Get a value and delete it atomically
+   */
+  take: <T>(key: string) => Promise<T | undefined>
+
+  /**
+   * Get a cached value or compute and store it (Laravel-style).
+   * TTL comes before callback (Laravel convention).
+   */
+  remember: <T>(key: string, ttl: number, callback: () => T | Promise<T>) => Promise<T>
+
+  /**
+   * Get a cached value or compute and store it forever (no expiration).
+   */
+  rememberForever: <T>(key: string, callback: () => T | Promise<T>) => Promise<T>
+
+  /**
+   * Get cache statistics
+   */
+  getStats: () => Promise<CacheStats>
+
+  /**
+   * Close the cache connection
+   */
+  close: () => Promise<void>
+
+  /**
+   * Disconnect from the cache (alias for close)
+   */
   disconnect: () => Promise<void>
+
+  /**
+   * Tag-aware writes. The returned scope mirrors the cache API but
+   * indexes every write under the supplied tag(s) so a single
+   * `flush()` can invalidate cascading entries together.
+   *
+   * @example
+   * ```ts
+   * await cache.tags(['user:42']).put('user:42:feed', payload, 300)
+   * await cache.tags(['user:42']).flush()
+   * ```
+   */
+  tags?: (tags: readonly string[]) => TaggedCacheScope
+}
+
+/**
+ * Returned by `cache.tags(tags)`. Tag-scoped writes/reads with a
+ * cascading `flush()`.
+ */
+export interface TaggedCacheScope {
+  put: <T>(key: string, value: T, ttl?: number) => Promise<boolean>
+  set: <T>(key: string, value: T, ttl?: number) => Promise<boolean>
+  setForever: <T>(key: string, value: T) => Promise<boolean>
+  remember: <T>(key: string, ttl: number, callback: () => T | Promise<T>) => Promise<T>
+  rememberForever: <T>(key: string, callback: () => T | Promise<T>) => Promise<T>
+  get: <T>(key: string) => Promise<T | undefined>
+  has: (key: string) => Promise<boolean>
+  flush: () => Promise<number>
+}
+
+/**
+ * Cache Statistics
+ */
+export interface CacheStats {
+  hits: number
+  misses: number
+  keys: number
+  size?: number
+  hitRate?: number
 }

package/src/chat.ts

@@ -191,23 +191,3 @@ export interface SlackResponse {
    */
   [key: string]: any
 }
-
-/**
- * Render options for templates
- */
-export interface RenderOptions {
-  /**
-   * Data to be used for template rendering
-   */
-  data?: Record<string, any>
-
-  /**
-   * Template engine options
-   */
-  engineOptions?: Record<string, any>
-
-  /**
-   * Additional rendering options
-   */
-  [key: string]: any
-}

package/src/cli.ts

@@ -174,6 +174,8 @@ export interface CliOptions {
    */
   background?: boolean
 
+  timeoutMs?: number
+
   startTime?: number
 
   /**
@@ -208,7 +210,6 @@ DomainsOptions
 
 export type BuildOption =
   | 'components'
-  | 'vueComponents'
   | 'webComponents'
   | 'elements'
   | 'functions'
@@ -267,7 +268,7 @@ export type GeneratorOption =
   | 'componentMeta'
   | 'coreSymlink'
   | 'openApiSpec'
-  | 'pkgxConfig'
+  | 'pantryConfig'
   | 'openapi'
   | 'modelFiles'
 export type GeneratorOptions = {
@@ -290,20 +291,24 @@ export type MakeBooleanOption =
   | 'model'
   | 'notification'
   | 'stack'
+  | 'middleware'
+  | 'dryRun'
+  | 'withValidation'
+  | 'withAuth'
 export type MakeOptions = {
   [key in MakeBooleanOption]: boolean
 } & {
   [key in MakeStringOption]: string
 } & CliOptions
 
-export type UpgradeBoolean = 'framework' | 'dependencies' | 'bun' | 'shell' | 'binary' | 'all' | 'force'
+export type UpgradeBoolean = 'framework' | 'dependencies' | 'bun' | 'shell' | 'binary' | 'all' | 'force' | 'canary' | 'stable' | 'noPostinstall' | 'postinstall'
 
-export type UpgradeString = 'version'
+export type UpgradeString = 'version' | 'from'
 
 export type UpgradeOptions = {
-  [key in UpgradeBoolean]: boolean
+  [key in UpgradeBoolean]?: boolean
 } & {
-  [key in UpgradeString]: string
+  [key in UpgradeString]?: string
 } & CliOptions
 
 export type ExamplesString = 'version'
@@ -314,7 +319,7 @@ export type ExamplesOptions = {
 } & {
   [key in ExamplesBoolean]: boolean
 } & CliOptions
-export type TestOptions = CliOptions & {
+export type TestingOptions = CliOptions & {
   ui?: boolean
   feature?: boolean
   unit?: boolean
@@ -388,10 +393,15 @@ export interface MigrateOptions extends CliOptions {
 
 export interface CliQueueOptions extends CliOptions {
   queue?: string
+  id?: string | number
+  all?: boolean
+  force?: boolean
+  connection?: string
 }
 
 export interface ReleaseOptions extends CliOptions {
   dryRun?: boolean
+  bump?: 'patch' | 'minor' | 'major' | 'prepatch' | 'preminor' | 'premajor' | 'prerelease' | string
 }
 export interface ProjectsOptions extends CliOptions {
   list?: boolean
@@ -412,9 +422,14 @@ export interface SearchCommandOptions extends CliOptions {
 
 export interface ScheduleOptions extends CliOptions {}
 
-export interface TinkerOptions extends CliOptions {}
+export interface TinkerOptions extends CliOptions {
+  eval?: string | boolean
+  print?: string | boolean
+  noBanner?: boolean
+  preload?: string
+}
 export interface TypesOptions extends CliOptions {}
 
-export type LibEntryType = 'vue-components' | 'web-components' | 'functions' | 'all'
+export type LibEntryType = 'web-components' | 'functions' | 'all'
 
 export type { CAC as CLI } from 'cac'

package/src/cloud.ts

@@ -270,7 +270,7 @@ type InfrastructureOptions = Partial<{
    *
    * These settings are used to configure the firewall.
    *
-   * @see https://stacksjs.org/docs/cloud#firewall
+   * @see https://stacksjs.com/docs/cloud#firewall
    *
    * @example
    * ```ts
@@ -327,8 +327,44 @@ type InfrastructureOptions = Partial<{
   cli: boolean
   docs: boolean
   fileSystem: boolean
+
+  /**
+   * **Tunnel Configuration**
+   *
+   * Deploy a custom tunnel server for sharing local dev servers.
+   * Only needed for custom domains — localtunnel.dev is the shared default.
+   *
+   * @example
+   * ```ts
+   * tunnel: {
+   *   enabled: true,
+   *   domain: 'tunnel.mycompany.com',
+   *   ssl: { enabled: true },
+   * }
+   * ```
+   */
+  tunnel: TunnelCloudConfig
 }>
 
+export interface TunnelCloudConfig {
+  /** Enable custom tunnel server deployment (opt-in) */
+  enabled: boolean
+  /** Custom domain for the tunnel server (must NOT be localtunnel.dev) */
+  domain?: string
+  /** AWS region to deploy to */
+  region?: string
+  /** EC2 instance type */
+  instanceType?: string
+  /** Resource name prefix */
+  prefix?: string
+  /** SSL configuration */
+  ssl?: {
+    enabled: boolean
+    porkbunApiKey?: string
+    porkbunSecretKey?: string
+  }
+}
+
 export interface CloudOptions {
   sites: {
     root: string
@@ -337,6 +373,9 @@ export interface CloudOptions {
   }
 
   infrastructure: InfrastructureOptions
+  cdn: any
+  api: any
+  firewall: any
 }
 
 export type CloudConfig = Partial<CloudOptions>

package/src/components.ts

@@ -1,5 +1,3 @@
-export type { Options as ComponentOptions } from 'unplugin-vue-components'
-
 export interface TagOption {
   /**
    * **Tag Name**
@@ -21,7 +19,7 @@ export interface TagOption {
    *     name: ['HelloWorld', 'AppHelloWorld'] // results in `<AppHelloWorld />`
    *   }]
    * }
-   * @see https://stacksjs.org/docs/components
+   * @see https://stacksjs.com/docs/components
    */
   name: string | string[]
 
@@ -35,7 +33,7 @@ export interface TagOption {
    * {
    *   name: 'HelloWorld' // results in `<HelloWorld />`
    * }
-   * @see https://stacksjs.org/docs/components
+   * @see https://stacksjs.com/docs/components
    */
   description?: string
 
@@ -53,7 +51,7 @@ export interface TagOption {
    *     description: 'The way to greet the user.',
    *   }
    * }
-   * @see https://stacksjs.org/docs/components
+   * @see https://stacksjs.com/docs/components
    */
   attributes?: {
     name: string

package/src/cron-jobs.ts

@@ -26,7 +26,7 @@ export enum Every {
   Year = '0 0 1 1 *',
 }
 
-export type JobHandler = (data?: any) => Promise<any> | any
+export type JobHandler = (_data?: any) => Promise<any> | any
 
 /**
  * Represents different backoff strategies for job retries

package/src/dashboard.ts

@@ -0,0 +1,40 @@
+/**
+ * **Dashboard Options**
+ *
+ * Controls which sections render in the `buddy dev --dashboard` sidebar.
+ * Every section defaults to enabled — set a flag to `false` in
+ * `config/dashboard.ts` to hide it (for example, projects that don't
+ * use commerce features set `commerce.enabled: false`).
+ *
+ * The `data` section is always visible (it's where every project's
+ * userland models live). It exposes per-row toggles for the basic
+ * built-in rows so a project can drop, say, the newsletter Subscribers
+ * row when there's no newsletter without losing the model viewer.
+ */
+export interface DashboardOptions {
+  /** Per-section visibility toggles. Omit a section to leave it enabled. */
+  sections?: {
+    library?: { enabled?: boolean }
+    content?: { enabled?: boolean }
+    commerce?: { enabled?: boolean }
+    marketing?: { enabled?: boolean }
+    analytics?: { enabled?: boolean }
+    management?: { enabled?: boolean }
+    utilities?: { enabled?: boolean }
+    /**
+     * Data section is always rendered (it hosts userland models). These
+     * sub-flags hide individual built-in rows. Userland model rows are
+     * always shown — they're the whole point of this section.
+     */
+    data?: {
+      dashboard?: { enabled?: boolean }
+      activity?: { enabled?: boolean }
+      users?: { enabled?: boolean }
+      teams?: { enabled?: boolean }
+      subscribers?: { enabled?: boolean }
+      allModels?: { enabled?: boolean }
+    }
+  }
+}
+
+export type DashboardConfig = Partial<DashboardOptions>

package/src/database.ts

@@ -1,6 +1,7 @@
+import type { SupportedDialect } from 'bun-query-builder'
 export interface DatabaseOptions {
-  default: string
-
+  default: SupportedDialect
+  logging?: boolean
   connections: {
     mysql?: {
       url?: string
@@ -39,6 +40,21 @@ export interface DatabaseOptions {
 
   migrations: string
   migrationLocks: string
+
+  // Query logging configuration
+  queryLogging?: {
+    enabled: boolean
+    slowThreshold: number // in milliseconds
+    retention: number // in days
+    pruneFrequency: number // in hours
+    excludedQueries?: string[] // patterns to exclude
+    analysis?: {
+      enabled: boolean
+      analyzeAll: boolean // analyze all queries, not just slow ones
+      explainPlan: boolean // collect EXPLAIN plans
+      suggestions: boolean // generate optimization suggestions
+    }
+  }
 }
 
 export type DatabaseConfig = Partial<DatabaseOptions>

package/src/dns.ts

@@ -362,7 +362,7 @@ export interface ContactInfo extends ContactDetail {
  * you may hover any of the options below and the definitions will be provided. In case
  * you have any questions, feel free to reach out via Discord or GitHub Discussions.
  *
- * @see https://stacksjs.org/docs/dns
+ * @see https://stacksjs.com/docs/dns
  */
 export interface DnsOptions {
   driver: 'aws'

package/src/docs.ts

@@ -1,7 +1,7 @@
-import type { UserConfig } from 'vitepress'
+import type { BunPressOptions } from '@stacksjs/bunpress'
 
-export interface DocsUserConfig extends UserConfig {
-  deploy: boolean
+export interface DocsUserConfig extends BunPressOptions {
+  deploy?: boolean
 }
 
 export type DocsConfig = DocsUserConfig