@stacksjs/orm 0.75.185 → 0.75.186

package/dist/define-model.d.ts

@@ -7,7 +7,7 @@ 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 { ApiMiddleware, DashboardModelOptions } from '@stacksjs/types';
+import type { ApiMiddleware, DashboardModelOptions, SearchEngineSearchParams } from '@stacksjs/types';
 import type { BelongsToForeignKeys } from './model-types';
 import type { Faker } from '@stacksjs/faker';
 import type { GdprTraitOptions, PersonalAttribute } from './gdpr/types';
@@ -53,6 +53,20 @@ export declare function withoutValidation<T>(fn: () => T | Promise<T>): Promise<
  * projecting each row, which is what a column-rearranging `shape` wants anyway.
  */
 export declare function projectDocumentsFromTrait(models: Record<string, unknown>[], config: SearchableTraitConfig): Promise<Record<string, unknown>[]>;
+/**
+ * Lightweight search-query builder returned by `Model.search()`
+ * (#1891). Thin wrapper around the search-engine driver — defers
+ * `.get()` / `.paginate()` / `.raw()` to the driver and lets
+ * callers attach filter / facet params via the standard search
+ * payload shape.
+ */
+declare function createSearchQueryBuilder(_baseModel: Record<string, unknown>, indexName: string, query: string, initialParams?: SearchEngineSearchParams, searchableFields?: readonly string[]): {
+  get: () => Promise<unknown[]>
+  paginate: (perPage: number, page?: number) => Promise<{ hits: unknown[], total: number, page: number, perPage: number }>
+  raw: () => Promise<unknown>
+  with: (params: SearchEngineSearchParams) => ReturnType<typeof createSearchQueryBuilder>
+  where: (filter: SearchFilter) => ReturnType<typeof createSearchQueryBuilder>
+};
 export declare function defineModel<const TDef extends ModelDefinition>(definition: TDef): StacksModelStatic<TDef>;
 /**
  * Normalize a ModelInstance (or array of them, or already-plain row) into
@@ -133,7 +147,8 @@ export declare interface StacksModelDefinition extends Omit<BQBModelDefinition,
   primaryKey?: string
   autoIncrement?: boolean
   dashboard?: DashboardModelOptions
-  traits?: Omit<NonNullable<BQBModelDefinition['traits']>, 'useApi'> & {
+  traits?: Omit<NonNullable<BQBModelDefinition['traits']>, 'useApi' | 'useSearch'> & {
+    useSearch?: boolean | SearchableTraitConfig
     useApi?: boolean | {
       readonly uri?: string
       readonly prefix?: string
@@ -163,10 +178,10 @@ export declare interface StacksModelDefinition extends Omit<BQBModelDefinition,
  */
 declare interface SearchableTraitConfig {
   index?: string
-  displayable?: string[]
-  searchable?: string[]
-  sortable?: string[]
-  filterable?: string[]
+  displayable?: readonly string[]
+  searchable?: readonly string[]
+  sortable?: readonly string[]
+  filterable?: readonly string[]
   shape?: (model: any) => Record<string, unknown> | null | undefined | Promise<Record<string, unknown> | null | undefined>
   shapeMany?: (models: any[]) => Record<string, unknown>[] | Promise<Record<string, unknown>[]>
   hidden?: Set<string>
@@ -330,58 +345,15 @@ declare type QueryModel<TDef extends ModelDefinition> = OrmModelStatic<QueryDefi
 declare type ModelWriteData<TDef extends ModelDefinition> = Parameters<QueryModel<TDef>['create']>[0];
 declare type ModelForceWriteData<TDef extends ModelDefinition> = Parameters<ReturnType<QueryModel<TDef>['make']>['forceFill']>[0]
   & Partial<BelongsToForeignKeys<QueryDefinition<TDef>>>;
-/**
- * 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: { fillable: true, validation: { rule: schema.string() } },
- *     views: { fillable: true, validation: { rule: schema.number() } },
- *   },
- *   belongsTo: ['Author'],
- *   hasMany: ['Tag', 'Category', 'Comment'],
- *   traits: { useTimestamps: true, useUuid: true },
- * })
- *
- * // Result: Post.where('title', 'test') — 'title' narrowed to valid columns
- * // Result: Post.with('author') — 'author' narrowed to valid relations
- * ```
- */
-// `update` and `delete` are omitted from the builder's surface because Stacks
-// installs its own (see addStaticHelpers). bun-query-builder 0.2.70 declares a
-// native static `update` returning a non-optional record; left in the
-// intersection its signature came first, so `await Model.update(id, data)` was
-// typed as never undefined while the method that actually runs returns
-// undefined for a row that is gone.
-export type StacksModelStatic<TDef extends ModelDefinition> = Omit<QueryModel<TDef>, 'update' | 'delete'> & TDef & TraitMethods & {
+/** Search statics exist precisely when the model enables the search trait. */
+export type ModelSearchStatics<TDef> = TDef extends { traits: { useSearch: infer TSearch } }
+  ? TSearch extends false | undefined ? {} : {
+    search: (query: string, params?: SearchEngineSearchParams) => ReturnType<typeof createSearchQueryBuilder>
+    makeAllSearchable: (chunkSize?: number) => Promise<number>
+    removeAllFromSearch: () => Promise<void>
+  }
+  : {}
+export type StacksModelStatic<TDef extends ModelDefinition> = Omit<QueryModel<TDef>, 'update' | 'delete'> & TDef & TraitMethods & ModelSearchStatics<TDef> & {
   readonly [MODEL_DEFINITION]: TDef
   update: (id: number | string, data: ModelWriteData<TDef>) => ReturnType<QueryModel<TDef>['find']>
   forceUpdate: (id: number | string, data: ModelForceWriteData<TDef>) => ReturnType<QueryModel<TDef>['find']>

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/orm",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.185",
+  "version": "0.75.186",
   "description": "The Stacks ORM integration",
   "author": "Chris Breuer",
   "contributors": [
@@ -63,31 +63,31 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/cache": "0.75.185",
-    "@stacksjs/cli": "0.75.185",
-    "@stacksjs/config": "0.75.185",
-    "@stacksjs/database": "0.75.185",
-    "@stacksjs/env": "0.75.185",
-    "@stacksjs/error-handling": "0.75.185",
-    "@stacksjs/events": "0.75.185",
-    "@stacksjs/logging": "0.75.185",
-    "@stacksjs/model-meta": "0.75.185",
-    "@stacksjs/pagination": "0.75.185",
-    "@stacksjs/path": "0.75.185",
-    "@stacksjs/query-builder": "0.75.185",
-    "@stacksjs/realtime": "0.75.185",
-    "@stacksjs/router": "0.75.185",
-    "@stacksjs/storage": "0.75.185",
-    "@stacksjs/strings": "0.75.185",
+    "@stacksjs/cache": "0.75.186",
+    "@stacksjs/cli": "0.75.186",
+    "@stacksjs/config": "0.75.186",
+    "@stacksjs/database": "0.75.186",
+    "@stacksjs/env": "0.75.186",
+    "@stacksjs/error-handling": "0.75.186",
+    "@stacksjs/events": "0.75.186",
+    "@stacksjs/logging": "0.75.186",
+    "@stacksjs/model-meta": "0.75.186",
+    "@stacksjs/pagination": "0.75.186",
+    "@stacksjs/path": "0.75.186",
+    "@stacksjs/query-builder": "0.75.186",
+    "@stacksjs/realtime": "0.75.186",
+    "@stacksjs/router": "0.75.186",
+    "@stacksjs/storage": "0.75.186",
+    "@stacksjs/strings": "0.75.186",
     "@stacksjs/ts-validation": "^0.5.6",
-    "@stacksjs/validation": "0.75.185",
+    "@stacksjs/validation": "0.75.186",
     "bun-query-builder": "^0.3.8"
   },
   "peerDependencies": {
-    "@stacksjs/auth": "0.75.185",
-    "@stacksjs/payments": "0.75.185",
-    "@stacksjs/queue": "0.75.185",
-    "@stacksjs/search-engine": "0.75.185",
+    "@stacksjs/auth": "0.75.186",
+    "@stacksjs/payments": "0.75.186",
+    "@stacksjs/queue": "0.75.186",
+    "@stacksjs/search-engine": "0.75.186",
     "stripe": "23.0.0"
   },
   "peerDependenciesMeta": {
@@ -108,7 +108,7 @@
     }
   },
   "devDependencies": {
-    "@stacksjs/types": "0.75.185",
+    "@stacksjs/types": "0.75.186",
     "better-dx": "^0.2.24",
     "stripe": "23.0.0"
   }