@stacksjs/orm 0.70.87 → 0.70.88

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/orm",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.87",
+  "version": "0.70.88",
   "description": "The Stacks ORM integration",
   "author": "Chris Breuer",
   "contributors": [
@@ -62,9 +62,9 @@
     "bun-query-builder": "^0.1.47"
   },
   "devDependencies": {
-    "@stacksjs/config": "0.70.87",
+    "@stacksjs/config": "0.70.88",
     "better-dx": "^0.2.16",
-    "@stacksjs/query-builder": "0.70.87",
-    "@stacksjs/types": "0.70.87"
+    "@stacksjs/query-builder": "0.70.88",
+    "@stacksjs/types": "0.70.88"
   }
 }

package/dist/auto-crud.d.ts

@@ -1,234 +0,0 @@
-/**
- * True when the error is a unique-constraint violation, across SQLite,
- * MySQL, and Postgres:
- *
- * - SQLite: `SQLITE_CONSTRAINT_UNIQUE` / `SQLITE_CONSTRAINT`
- * - MySQL: `errno: 1062` (ER_DUP_ENTRY)
- * - Postgres: `code: '23505'` (unique_violation)
- * - Generic fallback: message text match — covers wrapped errors from drivers
- *   that lose the structured code.
- *
- * Lives here (cycle-free `@stacksjs/orm`) rather than in `@stacksjs/auth`
- * because every framework write path needs it: auto-CRUD routes, commerce/cms
- * write functions, and `@stacksjs/auth`'s `register()` (which re-exports this
- * via './rbac-store-bqb' for back-compat). `@stacksjs/database` is NOT a valid
- * home — its drivers statically import `@stacksjs/orm`, so orm routes importing
- * from database would create a package cycle.
- *
- * Exported for direct unit testing and for callers that map duplicates to
- * their own error (e.g. `register()`'s 409) instead of swallowing them.
- */
-export declare function isUniqueViolation(err: unknown): boolean;
-/**
- * Classify a write-path error into an HTTP status + JSON body for the
- * auto-CRUD store/update handlers. Three branches, in priority order:
- *
- * 1. HttpError-like (an Error carrying an integer `status` in 400-599) —
- *    preserve its status, message and optional `details`. Duck-typed rather
- *    than `instanceof HttpError` so this helper stays inline-copyable into the
- *    canonical generated routes file without importing @stacksjs/error-handling.
- *    Covers the 400/413/422 throws from getRequestBody / validation.
- * 2. Unique-constraint violation — 409 with a clean `${Model} already exists`
- *    message (NO raw driver text, which would leak column names in prod).
- * 3. Anything else — the unchanged 500 contract, including `detail: String(err)`.
- */
-export declare function mapWriteError(err: unknown, modelName: string, op: 'create' | 'update'): { status: number, body: Record<string, unknown> };
-/**
- * Attribute names in model definitions may be camelCase; the migration
- * drivers (database/src/drivers/{sqlite,mysql,postgres}.ts) snake_case them
- * into column names. Write payload keys must be mapped the same way, LAST on
- * the write path — fillable filtering, validation, set-hooks and casts are
- * all keyed by attribute name. Output-identical to @stacksjs/strings
- * snakeCase for word-shaped attribute names (locked in by tests).
- */
-export declare function toSnakeCase(s: string): string;
-/** Map every key of a write payload to its snake_case column spelling. */
-export declare function toSnakeCaseKeys(data: Record<string, any>): Record<string, any>;
-/**
- * Filter a request body down to fillable fields. Accepts BOTH the
- * attribute-name spelling and its snake_case column spelling on input, so
- * read-modify-write round-trips work (GET responses expose snake_case
- * columns). The result stays keyed by attribute name — setters, casts and
- * validation rules all look fields up by that spelling.
- */
-export declare function filterFillable(body: any, fillableFields: string[]): Record<string, any>;
-/**
- * Drop attribute keys flagged `hidden: true` from an incoming write body.
- * Must drop BOTH spellings — accepting the snake spelling in filterFillable
- * without this would let `payment_intent_id` sneak past a camelCase hidden
- * marker.
- */
-export declare function dropHiddenInputs(data: Record<string, any>, hiddenFields: string[]): Record<string, any>;
-/**
- * Strip attribute keys flagged `hidden: true` from an outgoing response
- * record. Must drop BOTH spellings — DB rows come back keyed by snake_case
- * column names, so deleting only the attribute-name spelling lets a
- * camelCase hidden attribute (Transaction's `paymentDetails`) leak as
- * `payment_details` on public reads. Response-side mirror of
- * `dropHiddenInputs`.
- */
-export declare function stripHidden(record: any, hiddenFields: string[]): any;
-/**
- * Build the read-path column allowlist for a model: a map from BOTH the
- * attribute-name spelling and its snake_case column spelling to the real
- * snake_case column. One map serves `?sort=` and `?<column>=` filters.
- *
- * Why a map and not a set: attribute names may be camelCase
- * (`discountType`) while DB columns are always snake_case (the migration
- * drivers snake_case them — same contract as `toSnakeCaseKeys` on the
- * write path). A set keyed by attribute spelling let `?sort=discountType`
- * through to `orderBy('discountType')` (ghost column → 500) while
- * REJECTING the real column spelling `discount_type`. The map accepts
- * either spelling and always emits the column spelling.
- *
- * Hidden attributes are removed under BOTH spellings — sorting or
- * equality-filtering on a hidden column (`?two_factor_secret=x`) is a
- * blind-enumeration oracle even though the value never appears in the
- * response body.
- */
-export declare function buildReadColumnMap(attributes: Record<string, unknown> | null | undefined, hiddenFields: string[]): Map<string, string>;
-/**
- * Apply a `?sort=` parameter to a query builder chain. Comma-separated
- * tokens, each optionally `-` prefixed for descending. Tokens are resolved
- * through the `columns` allowlist map (see `buildReadColumnMap`) so either
- * spelling of a declared, non-hidden attribute works and everything else —
- * unknown names, hidden attributes, non-word tokens — is silently skipped
- * (the existing contract, matching the filter loop).
- *
- * Examples:
- *   ?sort=name              → ORDER BY name ASC
- *   ?sort=-rating           → ORDER BY rating DESC
- *   ?sort=discountType,name → ORDER BY discount_type ASC, name ASC
- */
-export declare function applySorting(query: any, sortParam: string | null, columns: ReadonlyMap<string, string>): any;
-declare function safeJSON(s: string): unknown;
-declare function safeJSONOrEmpty(_s: string): unknown;
-/**
- * Apply a model's `casts` to a record, in either direction:
- *   - `'get'`  — DB shape → JS-typed values (read responses)
- *   - `'set'`  — input → DB shape (write payloads)
- *
- * Casts are declared keyed by attribute name (possibly camelCase:
- * `instantBook: 'boolean'`) but DB rows come back keyed by snake_case
- * column names (`instant_book`) — so each cast is applied under BOTH
- * spellings, whichever is present. A record keyed by attribute names
- * (the write path) behaves exactly as before; a snake-keyed DB row (the
- * read path) now gets its casts instead of leaking raw SQLite `"1"`s.
- */
-export declare function applyCasts(record: Record<string, any> | null | undefined, casts: Record<string, string | { get: (v: unknown) => unknown, set: (v: unknown) => unknown }> | null | undefined, direction: 'get' | 'set'): any;
-/**
- * Resolve middleware lists for a model's `useApi` trait value (which may be
- * `true` or `{ uri, routes, middleware }`).
- *
- * Secure-by-default: mutating routes (store/update/destroy) get `auth`
- * unless the model explicitly declares `useApi.middleware` — an explicit
- * `middleware: []` is a deliberate opt-out and is honored (with a startup
- * warning at the call site). Read routes stay public unless declared.
- */
-export declare function resolveApiMiddleware(useApi: unknown): { read: string[], write: string[], declared: boolean };
-/**
- * Resolve `?page=` / `?per_page=` for the index route into a clamped,
- * NaN-safe `{ page, perPage, offset }`.
- *
- * - `page` is clamped to `>= 1` (a `?page=0` / negative would otherwise
- *   produce a negative OFFSET), defaulting to 1 on missing/NaN.
- * - `perPage` defaults to {@link INDEX_DEFAULT_PER_PAGE}, is clamped to
- *   `>= 1`, and capped at {@link INDEX_MAX_PER_PAGE}.
- */
-export declare function resolveIndexPageArgs(params: URLSearchParams): { page: number, perPage: number, offset: number };
-/**
- * Build the index pagination `meta`. `hasMore` is the source of truth for
- * "is there a next page" (derived by the route from a `LIMIT perPage + 1`
- * probe fetch), so `next_page_url` stays consistent whether or not a total
- * was counted. When `total` is known, `last_page` uses the
- * `Math.max(1, ceil(total / perPage))` floor from the Paginator interface.
- */
-export declare function buildIndexMeta(url: URL, page: number, perPage: number, rowCount: number, hasMore: boolean, total?: number): IndexPageMeta;
-/**
- * Flat Laravel paginator shape for the index response top level. Same values
- * as {@link buildIndexMeta} but keyed `current_page` (not `page`) so a
- * generated-endpoint list response deep-equals a `Model.paginate()` envelope.
- * The `page` -> `current_page` rename is the only delta; the value math lives
- * solely in `buildIndexMeta`.
- */
-export declare function buildIndexPaginator(url: URL, page: number, perPage: number, rowCount: number, hasMore: boolean, total?: number): IndexPaginator;
-/**
- * Columns every auto-CRUD table carries regardless of declared attributes.
- * Members of the read allowlist (sort/filter) alongside the model's own
- * attribute names.
- * @defaultValue `['id', 'uuid', 'created_at', 'updated_at', 'deleted_at']`
- */
-export declare const SYSTEM_COLUMNS: string[];
-/**
- * Built-in cast resolvers — kept in sync with @stacksjs/orm/define-model.
- * A duplicate here is the simplest way to keep auto-CRUD parity with the
- * model-driven path without introducing a circular import.
- * @defaultValue
- * ```ts
- * {
- *   string: { get: (v) => unknown | null, set: (v) => unknown | null },
- *   number: { get: (v) => unknown | null, set: (v) => unknown | null },
- *   integer: { get: (v) => unknown | null, set: (v) => unknown | null },
- *   float: { get: (v) => unknown | null, set: (v) => unknown | null },
- *   boolean: { get: (v) => boolean, set: (v) => number },
- *   json: { get: (v) => null | unknown, set: (v) => null | unknown },
- *   datetime: { get: (v) => Date | null, set: (v) => unknown },
- *   date: { get: (v) => Date | null, set: (v) => unknown },
- *   array: {
- *     get: (v) => never[] | unknown | unknown | never[],
- *     set: (v) => null | unknown
- *   }
- * }
- * ```
- */
-export declare const AUTO_CRUD_CASTERS: Record<string, { get: (v: unknown) => unknown, set: (v: unknown) => unknown }>;
-// Default page size for the auto-CRUD index route. Matches the
-// request-aware Model.paginate() / resolvePageArgs default (15) so the
-// REST list endpoint and the in-process paginator agree out of the box.
-export declare const INDEX_DEFAULT_PER_PAGE: 15;
-// Upper bound on ?per_page= so a single request can't ask for an
-// unbounded page and exhaust memory.
-export declare const INDEX_MAX_PER_PAGE: 100;
-/**
- * Pagination `meta` for the auto-CRUD index envelope (`{ data, meta }`).
- *
- * Always carries `page` / `per_page` / `from` / `to` / `has_more_pages`
- * plus `prev_page_url` / `next_page_url`. `total` / `last_page` and the
- * `first_page_url` / `last_page_url` are added only when a total is known
- * (`?with_count=true`).
- */
-export declare interface IndexPageMeta {
-  page: number
-  per_page: number
-  from: number | null
-  to: number | null
-  has_more_pages: boolean
-  prev_page_url: string | null
-  next_page_url: string | null
-  total?: number
-  last_page?: number
-  first_page_url?: string
-  last_page_url?: string
-}
-/**
- * Flat Laravel paginator shape lifted to the index response top level.
- * Mirrors {@link IndexPageMeta} minus `data`/`path` (the route spreads this
- * alongside its own `data`), but keys the current page as `current_page`
- * instead of `page` so a generated-endpoint list response deep-equals a
- * `Model.paginate()` envelope. `total` / `last_page` / `first_page_url` /
- * `last_page_url` stay gated on `total` (`?with_count=true`), matching
- * {@link SimplePaginator} when absent.
- */
-export declare interface IndexPaginator {
-  current_page: number
-  per_page: number
-  from: number | null
-  to: number | null
-  has_more_pages: boolean
-  prev_page_url: string | null
-  next_page_url: string | null
-  total?: number
-  last_page?: number
-  first_page_url?: string
-  last_page_url?: string
-}

package/dist/batch-loader.d.ts

@@ -1,19 +0,0 @@
-/**
- * Per-tick batched load against a Stacks model. The model object is the
- * batch identity — one queue per `model`. Ids posted in the same
- * microtask are merged into a single `findMany([...])` call.
- *
- * @example
- * ```ts
- * import { batchLoad } from '@stacksjs/orm'
- * import User from '~/app/Models/User'
- *
- * // Without batching: 100 SELECTs
- * for (const id of orderUserIds) await User.find(id)
- *
- * // With batching: 1 SELECT (`WHERE id IN (1, 2, … 100)`)
- * await Promise.all(orderUserIds.map(id => batchLoad(User, id)))
- * ```
- */
-// eslint-disable-next-line pickier/no-unused-vars
-export declare function batchLoad<T extends { findMany?: (ids: any[]) => Promise<any[]>, find?: (id: any) => Promise<any> }, K = number | string>(model: T, key: K): Promise<unknown>;

package/dist/db.d.ts

@@ -1,7 +0,0 @@
-/**
- * Database access re-export
- *
- * This module re-exports the db instance from @stacksjs/database
- * for convenience within the ORM package.
- */
-export { db } from '@stacksjs/database';

package/dist/define-model.d.ts

@@ -1,180 +0,0 @@
-import { createBillableMethods } from './traits/billable';
-import { createCategorizableMethods } from './traits/categorizable';
-import { createCommentableMethods } from './traits/commentable';
-import { createLikeableMethods } from './traits/likeable';
-import { createSoftDeleteMethods } from './traits/soft-deletes';
-import { createTaggableMethods } from './traits/taggable';
-import { createTwoFactorMethods } from './traits/two-factor';
-import { type OrmModelDefinition as BQBModelDefinition, type OrmModelStatic } from '@stacksjs/query-builder';
-import type { InferRelationNames } from '@stacksjs/query-builder';
-// Re-export types from bun-query-builder for convenience
-export type { ModelDefinition, InferRelationNames, ModelAttributes, InferModelAttributes, SystemFields, ColumnName, AttributeKeys, FillableKeys, HiddenKeys, ModelInstance, ModelQueryBuilder } from '@stacksjs/query-builder';
-/**
- * Run a callback with model lifecycle events suppressed for its entire
- * (synchronous + async) duration. Any nested awaits inside the callback
- * inherit the suppression via the AsyncLocalStorage propagation.
- *
- * @example
- * ```ts
- * await User.withoutEvents(async () => {
- *   for (const row of importedRows) await User.create(row) // no events fire
- * })
- * ```
- */
-export declare function withoutEvents<T>(fn: () => T | Promise<T>): Promise<T>;
-export declare function defineModel<const TDef extends ModelDefinition>(definition: TDef): StacksModelStatic<TDef>;
-/**
- * Normalize a ModelInstance (or array of them, or already-plain row) into
- * a serialization-ready plain object.
- *
- * Resolves the three shapes a Stacks model query can return:
- *   - ModelInstance (find/first/get)         → calls toJSON() → strips `hidden` attrs
- *   - Bare attribute bag with `_attributes`  → returns _attributes as-is
- *   - Plain row (already normalized)         → returns it unchanged
- *
- * Use `toAttrs(inst)` in actions instead of `inst._attributes ?? inst` —
- * the latter pattern silently leaks `hidden: true` fields (e.g. license_plate,
- * vin, password hashes) into responses.
- */
-export declare function toAttrs<T = any>(value: any): T;
-/**
- * Custom caster interface for user-defined attribute transformations.
- */
-export declare interface CasterInterface {
-  get(value: unknown): unknown
-  set(value: unknown): unknown
-}
-declare interface StacksModelDefinition extends Omit<BQBModelDefinition, 'attributes' | 'indexes' | 'traits'> {
-  name: string
-  table: string
-  primaryKey?: string
-  autoIncrement?: boolean
-  traits?: NonNullable<BQBModelDefinition['traits']> & Record<string, unknown>
-  indexes?: Array<{ name: string, columns: string[], unique?: boolean, where?: string }>
-  casts?: Record<string, CastType | CasterInterface>
-  attributes: {
-    [key: string]: {
-      factory?: (faker: any) => any
-      [key: string]: any
-    }
-  }
-  [key: string]: any
-}
-export declare interface TraitMethods {
-  _taggable?: ReturnType<typeof createTaggableMethods>
-  _categorizable?: ReturnType<typeof createCategorizableMethods>
-  _commentable?: ReturnType<typeof createCommentableMethods>
-  _billable?: ReturnType<typeof createBillableMethods>
-  _likeable?: ReturnType<typeof createLikeableMethods>
-  _twoFactor?: ReturnType<typeof createTwoFactorMethods>
-  _softDeletes?: ReturnType<typeof createSoftDeleteMethods>
-}
-/**
- * Built-in cast types for model attributes.
- *
- * ### Timezone contract (stacksjs/stacks#1876 O-5, D-5)
- *
- * `datetime` and `date` casts persist values in **UTC** regardless of
- * which driver is connected. The `set` direction uses
- * `Date.toISOString()`, which always emits `Z`-suffixed UTC. The
- * `get` direction parses the stored string back into a JavaScript
- * `Date`, which represents an instant on the universal timeline —
- * timezone presentation is the caller's responsibility (typically via
- * `Intl.DateTimeFormat` at the render layer, or a Temporal-API
- * adapter).
- *
- * **Why UTC-only:** Per-driver behavior diverges sharply on
- * timezone-aware columns. PostgreSQL has `timestamptz` (timezone-
- * aware); MySQL stores `TIMESTAMP` as UTC but presents in the
- * session timezone; SQLite has no timezone concept at all and stores
- * ISO strings verbatim. The ORM normalizes them to a single
- * convention (UTC on the wire) so multi-driver apps behave the same
- * across environments. Apps that need original-timezone preservation
- * should store the user's TZ as a separate column and convert at
- * the render layer.
- */
-export type CastType = 'string' | 'number' | 'boolean' | 'json' | 'datetime' | 'date' | 'array' | 'integer' | 'float';
-declare type ModelDefinition = StacksModelDefinition;
-/**
- * Stacks-enhanced model definition.
- *
- * Wraps bun-query-builder's `createModel()` with:
- * - Event dispatching via `traits.observe`
- * - Trait methods (billable, taggable, categorizable, commentable, likeable, 2FA)
- * - Full backward compatibility with generators (migration, routes, dashboard)
- *
- * ### Relationships
- * Each entry in `belongsTo`, `hasMany`, `hasOne`, `belongsToMany`,
- * `hasOneThrough`, and `hasManyThrough` declares a typed relation
- * usable via `.with('relationName')`:
- *
- * ```ts
- * defineModel({
- *   belongsTo: ['Author'],     // ↪ post.author
- *   hasMany:   ['Comment'],    // ↪ post.comments (lowercase + pluralized)
- *   hasOne:    ['Cover'],      // ↪ post.cover
- * })
- * ```
- *
- * After eager loading the related row(s) are reachable as a property
- * on the instance — `(await Post.with('author').first()).author`.
- *
- * @example
- * ```ts
- * import { defineModel } from '@stacksjs/orm'
- * import { schema } from '@stacksjs/validation'
- *
- * export default defineModel({
- *   name: 'Post',
- *   table: 'posts',
- *   attributes: {
- *     title: { type: 'string', fillable: true, validation: { rule: schema.string() } },
- *     views: { type: 'number', fillable: true, validation: { rule: schema.number() } },
- *   },
- *   belongsTo: ['Author'],
- *   hasMany: ['Tag', 'Category', 'Comment'],
- *   traits: { useTimestamps: true, useUuid: true },
- * } as const)
- *
- * // Result: Post.where('title', 'test') — 'title' narrowed to valid columns
- * // Result: Post.with('author') — 'author' narrowed to valid relations
- * ```
- */
-export type StacksModelStatic<TDef extends ModelDefinition> = OrmModelStatic<TDef> & TDef & TraitMethods & {
-  update: (id: number | string, data: Record<string, unknown>) => ReturnType<OrmModelStatic<TDef>['find']>
-  forceUpdate: (id: number | string, data: Record<string, unknown>) => ReturnType<OrmModelStatic<TDef>['find']>
-  forceCreate: (data: Record<string, unknown>) => ReturnType<OrmModelStatic<TDef>['create']>
-  delete: (id: number | string) => Promise<boolean>
-  withoutEvents: <T>(fn: () => T | Promise<T>) => Promise<T>
-}
-/**
- * Thrown by `Model.findOrFail(id)` (and other strict lookups) when no row matches.
- * Callers can `instanceof` against this to distinguish "missing" from other errors.
- */
-export declare class ModelNotFoundError extends Error {
-  readonly model: string;
-  readonly id: number | string | undefined;
-  constructor(model: string, id?: number | string);
-}
-/**
- * Thrown when a write payload (`Model.create` / `Model.update` /
- * `firstOrCreate` / `updateOrCreate`) contains an attribute the model
- * forbids from mass assignment. There are two reasons this fires:
- *
- *   • `guarded`  — the attribute is explicitly marked `guarded: true`.
- *   • `not-fillable` — the model is in *allowlist* mode (at least one
- *     attribute has `fillable: true`) and the write payload contains a
- *     non-allowlisted field.
- *
- * The check exists to stop unfiltered request payloads from landing
- * directly in the DB. If you genuinely need to write a normally-protected
- * column, use the `force*` escape hatches (`Model.forceCreate(...)`,
- * `Model.forceUpdate(id, ...)`) — those bypass the check by design and
- * make the bypass auditable in code review.
- */
-export declare class MassAssignmentException extends Error {
-  readonly model: string;
-  readonly attribute: string;
-  readonly reason: 'guarded' | 'not-fillable';
-  constructor(model: string, attribute: string, reason: 'guarded' | 'not-fillable');
-}

package/dist/generate-database-schema.d.ts

@@ -1,23 +0,0 @@
-/**
- * Walk userland + framework-default models, return the rendered
- * `database/types.d.ts` content plus a structured per-table summary
- * the CLI can render.
- */
-export declare function buildDatabaseSchema(options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
-/**
- * Pure renderer — for tests that don't want to round-trip through the
- * model loader.
- */
-export declare function renderDatabaseTypeFile(tables: Array<{ table: string, columns: Record<string, string> }>): string;
-export declare interface GenerateSchemaOptions {
-  modelsDir?: string
-  defaultsDir?: string
-  outFile?: string
-  dryRun?: boolean
-}
-export declare interface GenerateSchemaResult {
-  outFile: string
-  tables: Array<{ table: string, model: string, columns: Record<string, string> }>
-  errors: Array<{ file: string, error: string }>
-  content: string
-}