@stacksjs/orm 0.70.44 → 0.70.53

package/dist/src/model-types.d.ts

@@ -1,4 +1,4 @@
-import type { InferModelAttributes, ModelAttributes, ModelDefinition } from 'bun-query-builder';
+import type { AttributeKeys, ColumnName, FillableKeys, InferModelAttributes, ModelAttributes, ModelDefinition } from '@stacksjs/query-builder';
 /**
  * Extract the raw ModelDefinition from a defineModel() return value.
  * Uses the getDefinition() accessor that defineModel() provides.
@@ -8,6 +8,7 @@ export type Def<T> = T extends { getDefinition: () => infer D extends ModelDefin
  * Extract foreign key columns from belongsTo relations.
  * e.g., belongsTo: ['Customer', 'Coupon'] → { customer_id: number, coupon_id: number }
  */
+// eslint-disable-next-line ts/no-empty-object-type
 export type BelongsToForeignKeys<TDef> = TDef extends { readonly belongsTo: readonly (infer R extends string)[] }
     ? { [K in R as `${Lowercase<K>}_id`]: number }
     : {}
@@ -17,24 +18,72 @@ export type BelongsToForeignKeys<TDef> = TDef extends { readonly belongsTo: read
  * @example
  * import type { ModelRow } from '@stacksjs/orm'
  * import type Post from '../models/Post'
- * type PostJsonResponse = ModelRow<Post>
+ * type PostJsonResponse = ModelRow<typeof Post>
  */
 export type ModelRow<T> = ModelAttributes<Def<T>> & BelongsToForeignKeys<Def<T>>;
+/**
+ * Same as {@link ModelRow} but with every field optional. Useful for
+ * partial-projection reads (`select('id', 'name')`) and test fixtures
+ * that don't bother populating every column.
+ */
+export type ModelRowLoose<T> = Partial<ModelRow<T>>;
 /**
  * Insertable data type: model attributes + FK columns, all optional.
  *
  * @example
  * import type { NewModelData } from '@stacksjs/orm'
  * import type Post from '../models/Post'
- * type NewPost = NewModelData<Post>
+ * type NewPost = NewModelData<typeof Post>
  */
 export type NewModelData<T> = Partial<InferModelAttributes<Def<T>> & BelongsToForeignKeys<Def<T>>>;
+/**
+ * Strict insertable shape: only attributes marked `fillable: true` in
+ * the model definition (plus belongsTo foreign keys), partial because
+ * many fillable columns have factory defaults at the DB layer.
+ *
+ * Use this when you want compile-time enforcement that consumers
+ * can't pass non-fillable fields to `create()` / `insert()`.
+ * {@link NewModelData} is the looser sibling that allows any attribute.
+ */
+export type ModelCreateData<T> = Partial<Pick<InferModelAttributes<Def<T>>, Extract<FillableKeys<Def<T>>, keyof InferModelAttributes<Def<T>>>> & BelongsToForeignKeys<Def<T>>>;
+/** Loose variant of {@link ModelCreateData} — same shape as {@link NewModelData}, aliased for naming-parity with the row types. */
+export type ModelCreateDataLoose<T> = NewModelData<T>;
 /**
  * Updateable data type: model attributes + FK columns, all optional.
  *
  * @example
  * import type { UpdateModelData } from '@stacksjs/orm'
  * import type Post from '../models/Post'
- * type PostUpdate = UpdateModelData<Post>
+ * type PostUpdate = UpdateModelData<typeof Post>
  */
 export type UpdateModelData<T> = Partial<InferModelAttributes<Def<T>> & BelongsToForeignKeys<Def<T>>>;
+/**
+ * Just the attribute records flagged `fillable: true` — useful for
+ * code-generators and any helper that needs the typed shape of a
+ * model's fillable-attribute config (e.g., admin form schemas).
+ */
+export type InferFillableAttributes<T> = {
+  [K in Extract<FillableKeys<Def<T>>, keyof Def<T>['attributes']>]: Def<T>['attributes'][K]
+}
+/**
+ * Every valid column name for the model (attributes + system fields
+ * added by traits like `id`, `uuid`, `created_at`). Useful for
+ * constraining query builders that accept a `column` parameter.
+ */
+export type InferColumnNames<T> = ColumnName<Def<T>>;
+/**
+ * Attribute keys whose `type` is declared as `'number'` in the model
+ * definition. Used to constrain aggregate methods (`sum`, `avg`,
+ * `min`, `max`) so they can't be called against string columns.
+ *
+ * Models that don't declare an explicit `type` per attribute (the
+ * common case — most validation rules are inferred from
+ * `schema.number()` chains, not declared on `type`) fall back to
+ * `AttributeKeys<Def<T>>` here. Tighten by declaring `type: 'number'`
+ * on the attribute spec when narrowing matters.
+ */
+export type InferNumericColumns<T> = {
+  [K in AttributeKeys<Def<T>>]: Def<T>['attributes'][K] extends { type: 'number' } ? K : never
+}[AttributeKeys<Def<T>>] extends infer R
+  ? [R] extends [never] ? AttributeKeys<Def<T>> : R
+  : never;

package/dist/src/paginator-request.d.ts

@@ -0,0 +1,68 @@
+import type { CursorPaginator, Paginator, SimplePaginator } from './paginator';
+/**
+ * Resolve `[perPage, page]` for `Model.paginate(...)`. Precedence:
+ *
+ *   1. Explicit positional arg from the caller (`Model.paginate(20, 3)`).
+ *   2. `?per_page=` / `?page=` from the active request (auto-magic).
+ *   3. Defaults: `perPage = 15`, `page = 1`.
+ *
+ * `perPage` from the query string is clamped to `[1, DEFAULT_MAX_PER_PAGE]`.
+ * Explicit positional `perPage` is trusted as-is (the caller is the app,
+ * not an untrusted client).
+ *
+ * `page` is clamped to `>= 1` from both sources to avoid `OFFSET -X`-style
+ * negatives reaching the driver.
+ */
+export declare function resolvePageArgs(perPageArg?: number, pageArg?: number): ResolvedPageArgs;
+/**
+ * Resolve cursor args for `Model.cursorPaginate(...)`. Precedence
+ * mirrors {@link resolvePageArgs} — explicit > `?cursor=` > null.
+ *
+ * Cursor values that arrive via the query string (always strings) are
+ * fed through {@link parseCursor} so a composite cursor encoded as
+ * `JSON.stringify([val1, val2])` reaches bqb as a real array — bqb's
+ * `sql(cursor)` interpolation expects an array when the `column` arg
+ * is an array (composite-key pagination). Without this parse, the
+ * cursor round-trip breaks: serialize → string → wire → string →
+ * bqb thinks it's a primitive → wrong query.
+ */
+export declare function resolveCursorArgs(perPageArg?: number, cursorArg?: string | number | unknown[] | null): { perPage: number, cursor: unknown };
+/**
+ * Parse a cursor value into the shape bqb's `cursorPaginate` expects.
+ *
+ *   - `null` / `undefined` → `null` (first page, no WHERE clause)
+ *   - Already an array → returned as-is (composite cursor, native form)
+ *   - String starting with `[` → JSON-parsed back into an array
+ *     (composite cursor that was serialized for the wire format)
+ *   - All other strings / primitives → returned as-is (single-column
+ *     cursor)
+ *
+ * This is the missing piece in the wire-format round-trip:
+ * {@link toCursorPaginator} encodes composite cursors with
+ * `JSON.stringify` so they survive a URL query param round-trip, and
+ * this function decodes them on the way back in.
+ */
+export declare function parseCursor(value: string | number | unknown[] | null | undefined): unknown;
+/**
+ * Fill in `path`, `prev_page_url`, `next_page_url` (and `first_page_url`
+ * / `last_page_url` for the full {@link Paginator}) from the active
+ * request URL. Mutates the paginator in place and returns it for chaining.
+ *
+ * No-op when no request is in scope — keeps CLI / queue / cron callers
+ * unaffected. Preserves all OTHER query params on the request so search
+ * filters survive across page navigations (`?status=active&page=2` →
+ * `next_page_url` includes `status=active`).
+ */
+export declare function enrichPaginatorUrls<T>(paginator: Paginator<T>): Paginator<T>;
+export declare function enrichPaginatorUrls<T>(paginator: SimplePaginator<T>): SimplePaginator<T>;
+export declare function enrichPaginatorUrls<T>(paginator: CursorPaginator<T>): CursorPaginator<T>;
+/** Test helper — reset the lazy-import cache (for tests that mock the
+ *  router module after first access). */
+export declare function __resetRequestContextCache(): void;
+/**
+ * Resolved pagination args ready to pass to bqb's `paginate(perPage, page)`.
+ */
+export declare interface ResolvedPageArgs {
+  perPage: number
+  page: number
+}

package/dist/src/paginator.d.ts

@@ -0,0 +1,99 @@
+/** Duck-typed shape check — used by the response serializer (P4) to
+ *  detect a paginator-shaped return value from an action. */
+export declare function isPaginator<T = unknown>(value: unknown): value is Paginator<T>;
+/** Duck-typed shape check for the simple paginator. */
+export declare function isSimplePaginator<T = unknown>(value: unknown): value is SimplePaginator<T>;
+/** Duck-typed shape check for the cursor paginator. */
+export declare function isCursorPaginator<T = unknown>(value: unknown): value is CursorPaginator<T>;
+/**
+ * Convert bun-query-builder's `paginate()` output (`{ data, meta:
+ * { perPage, page, total, lastPage } }`) into the canonical Stacks
+ * shape. P1 of the migration — the URL fields stay undefined until
+ * P2 wires the request-context resolver.
+ */
+export declare function toPaginator<T>(result: { data: T[], meta: { perPage: number, page: number, total: number, lastPage: number } }): Paginator<T>;
+/** Convert bqb's `simplePaginate()` output to the canonical
+ *  {@link SimplePaginator} shape. */
+export declare function toSimplePaginator<T>(result: { data: T[], meta: { perPage: number, page: number, hasMore: boolean } }): SimplePaginator<T>;
+/** Convert bqb's `cursorPaginate()` output to the canonical
+ *  {@link CursorPaginator} shape. Cursors are serialized to strings
+ *  via JSON — composite cursors (arrays) survive the round-trip. */
+export declare function toCursorPaginator<T>(result: { data: T[], meta: { perPage: number, nextCursor: unknown, prevCursor: unknown } }): CursorPaginator<T>;
+/**
+ * Canonical paginator types + adapters (stacksjs/stacks#1905, P1 from #1910).
+ *
+ * Four pagination shapes used to ship across the framework — bqb's SQL
+ * client `{ data, meta }`, bqb's sync ORM `{ data, total, page, ... }`,
+ * the search-engine's `{ hits, total, page, perPage }`, and a fifth
+ * declared-but-not-implemented Stacks shape (`{ data, paging, next_cursor }`)
+ * that the runtime never actually produced. This module unifies them
+ * to the Laravel-flavored, snake_case shapes below.
+ *
+ * P1 ships only `data` + counts; the URL fields are declared but left
+ * `undefined` by default. P2 (stacksjs/stacks#1906) wires them in when
+ * a request is in scope.
+ *
+ * Shape choices:
+ *   - snake_case for JSON friendliness (matches Laravel's serialized
+ *     paginator + the existing REST convention across the Stacks API)
+ *   - `from` / `to` are 1-indexed offsets of the first/last row on the
+ *     current page; `null` when the page is empty
+ *   - `has_more_pages` is the cheap boolean apps actually want — saves
+ *     `current_page < last_page` checks everywhere
+ */
+/**
+ * Full paginator — knows the total row count so it can compute
+ * `last_page`, supports "jump to page N" UI patterns. Costs an extra
+ * `COUNT(*)` query; use {@link SimplePaginator} or {@link CursorPaginator}
+ * for very large tables.
+ */
+export declare interface Paginator<T> {
+  data: T[]
+  current_page: number
+  per_page: number
+  total: number
+  last_page: number
+  from: number | null
+  to: number | null
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  first_page_url?: string
+  last_page_url?: string
+  path?: string
+}
+/**
+ * Simple paginator — drops the `COUNT(*)` query. Faster on large tables
+ * but can't render "jump to page 5" UIs since `last_page` / `total` are
+ * unknown. Suitable for infinite-scroll feeds.
+ */
+export declare interface SimplePaginator<T> {
+  data: T[]
+  current_page: number
+  per_page: number
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  path?: string
+}
+/**
+ * Cursor (keyset) paginator — uses `WHERE id > :cursor` ordering rather
+ * than `LIMIT/OFFSET`, so query cost stays constant regardless of how
+ * deep the user has paged. The trade-off is no random-access ("jump to
+ * page N"); only prev/next.
+ *
+ * Cursor values are opaque to the caller — serialize as JSON, send to
+ * the client, accept back unchanged. Implementations (cursorPaginate)
+ * decide the cursor shape (single column value, base64 tuple for
+ * composite keys, etc.).
+ */
+export declare interface CursorPaginator<T> {
+  data: T[]
+  per_page: number
+  next_cursor: string | null
+  prev_cursor: string | null
+  has_more_pages: boolean
+  prev_page_url?: string | null
+  next_page_url?: string | null
+  path?: string
+}

package/dist/src/traits/audit.d.ts

@@ -20,6 +20,14 @@ export declare function setAuditUser(id: number | string | null): void;
  * the model's write methods.
  */
 export declare function createAuditMethods(modelName: string): AuditHelpers;
+/**
+ * Resolve the transactional opt-in from a model's `traits.useAudit`
+ * declaration. Accepts both `true` (default, best-effort) and
+ * `{ transactional: true }` (audit failures roll back the user's
+ * write). Centralized so the wrapper functions below have a single
+ * boolean to check.
+ */
+export declare function resolveAuditOptions(useAudit: unknown): { transactional: boolean };
 /**
  * Wire the audit trait into a model's static surface. Wraps `create`,
  * `update`, and `delete` so each one writes a `model_audits` row after a
@@ -31,15 +39,24 @@ export declare function createAuditMethods(modelName: string): AuditHelpers;
  * we wrap the final composed function rather than something that gets
  * shadowed later.
  *
+ * **Transactional opt-in (stacksjs/stacks#1876 X-2):** pass
+ * `{ transactional: true }` to wrap each create/update/delete in a
+ * `db.transaction(...)` so audit-row write failures roll back the
+ * underlying user write. Default is best-effort (audit failures are
+ * logged but don't abort the operation) — appropriate for a debug /
+ * change-log use case but NOT for compliance scenarios where a missing
+ * audit entry is itself a failure mode.
+ *
  * @example
  * ```ts
- * // Inside defineModel():
- * if (definition.traits?.useAudit) {
- *   applyAudit(baseModel, definition)
- * }
+ * // Best-effort (default): audit failures don't abort writes.
+ * defineModel({ traits: { useAudit: true } })
+ *
+ * // Transactional (compliance): audit failures roll back the write.
+ * defineModel({ traits: { useAudit: { transactional: true } } })
  * ```
  */
-export declare function applyAudit(baseModel: Record<string, unknown>, modelName: string, primaryKey?: string): void;
+export declare function applyAudit(baseModel: Record<string, unknown>, modelName: string, primaryKey?: string, opts?: { transactional?: boolean }): void;
 export declare interface AuditHelpers {
   audits: (id: number | string) => Promise<Array<Record<string, unknown>>>
 }

package/dist/src/traits/billable.d.ts

@@ -1 +1,37 @@
+import type Stripe from 'stripe';
 export declare function createBillableMethods(_tableName: string): void;
+/**
+ * Stored subscription row shape — narrower than `Record<string, unknown>`
+ * so callers get autocompletion on the common fields without us
+ * importing the full `subscriptions` model type (which would pull in
+ * a circular @stacksjs/orm dependency). Keep in sync with the schema
+ * in `database/src/custom/subscriptions.ts`.
+ */
+export declare interface StoredSubscriptionRow {
+  id: number
+  user_id: number
+  type: string
+  provider_id: string
+  provider_status: string
+  provider_price_id?: string
+  unit_price?: number
+  quantity?: number
+  trial_ends_at?: string
+  ends_at?: string
+  provider_type?: string
+  last_used_at?: string
+}
+/**
+ * Return shape for `newSubscription` / `updateSubscription` — pairs
+ * the Stripe-side subscription with the most-recent payment intent so
+ * callers can immediately handle 3DS / SCA flows without a second
+ * round-trip to Stripe.
+ */
+export declare interface NewSubscriptionResult {
+  subscription: Stripe.Response<Stripe.Subscription>
+  paymentIntent?: Stripe.PaymentIntent
+}
+export declare interface ActiveSubscriptionResult {
+  subscription: StoredSubscriptionRow
+  providerSubscription: Stripe.Response<Stripe.Subscription>
+}

package/dist/src/traits/categorizable.d.ts

@@ -1 +1,5 @@
+// `db` is a Proxy whose methods are typed via bun-query-builder's generics —
+// resolution to the concrete invocation here can leave methods marked
+// `T | undefined` under strict null checks. Cast through `any` so the trait
+// helpers can call the runtime-defined methods without a guard at every site.
 export declare function createCategorizableMethods(tableName: string): void;

package/dist/src/types.d.ts

@@ -1,3 +1,4 @@
+import type { CursorPaginator, Paginator, SimplePaginator } from './paginator';
 import type { Operator } from './subquery';
 export declare interface OrmDriver<T = unknown> {
   find: (id: number) => Promise<T | undefined>
@@ -39,11 +40,14 @@ export declare interface SelectedQuery<TTable, TJson, K extends string> {
   get(): Promise<SelectedResult<TJson, K>[]>
   latest(column?: keyof TTable): Promise<SelectedResult<TJson, K> | undefined>
   oldest(column?: keyof TTable): Promise<SelectedResult<TJson, K> | undefined>
-  paginate(options?: { limit?: number, offset?: number, page?: number }): Promise<{
-    data: SelectedResult<TJson, K>[]
-    paging: { total_records: number, page: number, total_pages: number }
-    next_cursor: number | null
-  }>
+  paginate(perPage?: number, page?: number): Promise<Paginator<SelectedResult<TJson, K>>>
+  simplePaginate(perPage?: number, page?: number): Promise<SimplePaginator<SelectedResult<TJson, K>>>
+  cursorPaginate(
+    perPage?: number,
+    cursor?: string | number | unknown[] | null,
+    column?: keyof TTable | (keyof TTable)[],
+    direction?: 'asc' | 'desc',
+  ): Promise<CursorPaginator<SelectedResult<TJson, K>>>
   chunk(size: number, callback: (models: SelectedResult<TJson, K>[]) => Promise<void>): Promise<void>
   pluck<PK extends Extract<K | 'id', keyof TJson>>(field: PK): Promise<TJson[PK][]>
   max(field: keyof TTable): Promise<number>

package/dist/src/utils.d.ts

@@ -14,7 +14,7 @@ export declare function getGuardedAttributes(model: Model): string[];
 export declare function getFillableAttributes(model: Model, otherModelRelations: RelationConfig[]): string[];
 export declare function extractFields(model: Model, modelFile: string): Promise<ModelElement[]>;
 export declare function mapEntity(attribute: ModelElement): string | undefined;
-export declare function extractImports(filePath: string): string[];
+export declare function extractImports(filePath: string): Promise<string[]>;
 export declare function extractAttributesFromModel(filePath: string): Promise<AttributesElements>;
 export declare function findCoreModel(modelName: string): string;
 export declare function findUserModel(modelName: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/orm",
   "type": "module",
-  "version": "0.70.44",
+  "version": "0.70.53",
   "description": "The Stacks ORM integration",
   "author": "Chris Breuer",
   "contributors": [
@@ -29,6 +29,10 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
+    "./traits/*": {
+      "bun": "./src/traits/*.ts",
+      "types": "./dist/src/traits/*.d.ts"
+    },
     "./*": {
       "bun": "./src/*",
       "import": "./dist/*"
@@ -46,14 +50,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/ts-validation": "^0.4.9",
-    "bun-query-builder": "^0.1.21"
+    "@stacksjs/ts-validation": "^0.5.0",
+    "bun-query-builder": "^0.1.38"
   },
   "devDependencies": {
-    "@stacksjs/build": "^0.70.44",
-    "@stacksjs/config": "^0.70.44",
+    "@stacksjs/build": "workspace:*",
+    "@stacksjs/config": "0.70.53",
     "better-dx": "^0.2.12",
-    "@stacksjs/query-builder": "^0.70.44",
-    "@stacksjs/types": "^0.70.44"
+    "@stacksjs/query-builder": "0.70.53",
+    "@stacksjs/types": "0.70.53"
   }
 }