@onyx.dev/onyx-database 1.0.3 → 1.1.0

package/README.md

@@ -20,6 +20,7 @@ TypeScript client SDK for **Onyx Cloud Database** — a zero-dependency, strict-
 - [Initialize the client](#initialize-the-client)
 - [Generate schema types](#optional-generate-typescript-types-from-your-schema)
 - [Query helpers](#query-helpers-at-a-glance)
+- [Full-text search](#full-text-search-lucene)
 - [Examples](#usage-examples-with-user-role-permission)
 - [Error handling](#error-handling)
 - [HTTP retries](#http-retries)
@@ -410,7 +411,7 @@ import {
   between,
   gt, gte, lt, lte,
   like, notLike, contains, notContains,
-  startsWith, notStartsWith, matches, notMatches,
+  startsWith, notStartsWith, matches, notMatches, search,
   isNull, notNull,
   asc, desc
 } from '@onyx.dev/onyx-database';
@@ -418,6 +419,7 @@ import {
 
 - Prefer `within`/`notWithin` for inclusion checks (supports arrays, comma-separated strings, or inner queries).  
 - `inOp`/`notIn` remain available for backward compatibility and are exact aliases.
+- `search(text, minScore?)` builds a Lucene `MATCHES` predicate on `__full_text__` and always serializes `minScore` (null when omitted).
 
 ### Inner queries (IN/NOT IN with sub-selects)
 
@@ -453,6 +455,36 @@ const rolesMissingPermission = await db
 
 ---
 
+## Full-text search (Lucene)
+
+Use `.search(text, minScore?)` on a query builder for table-level full-text search, or call `db.search(...)` to target **all** tables (`table = "ALL"` in the request body). The search value always includes `minScore` and falls back to `null` when you omit it.
+
+```ts
+import { desc, eq, onyx, search, tables, type Schema } from '@onyx.dev/onyx-database';
+
+const db = onyx.init<Schema>();
+
+// Table-specific search with a minimum score
+const recentUsers = await db
+  .from(tables.User)
+  .search('user bio text', 4.4)
+  .orderBy(desc('createdAt'))
+  .limit(5)
+  .list();
+
+// Search across all tables (table: "ALL")
+const acrossTables = await db.search('user bio text').list({ pageSize: 5 });
+
+// Combine a search predicate with other filters
+const activeMatch = await db
+  .from(tables.User)
+  .where(search('user bio text'))
+  .and(eq('isActive', true))
+  .firstOrNull();
+```
+
+---
+
 ## Usage examples with `User`, `Role`, `Permission`
 
 > The examples assume your schema has tables named `User`, `Role`, and `Permission`.  

package/dist/{aggregates-BGXzij4U.d.cts → aggregates-DodZNu9-.d.cts}

@@ -7,6 +7,11 @@
  * ```
  */
 type QueryCriteriaOperator = 'EQUAL' | 'NOT_EQUAL' | 'IN' | 'NOT_IN' | 'GREATER_THAN' | 'GREATER_THAN_EQUAL' | 'LESS_THAN' | 'LESS_THAN_EQUAL' | 'MATCHES' | 'NOT_MATCHES' | 'BETWEEN' | 'LIKE' | 'NOT_LIKE' | 'CONTAINS' | 'CONTAINS_IGNORE_CASE' | 'NOT_CONTAINS' | 'NOT_CONTAINS_IGNORE_CASE' | 'STARTS_WITH' | 'NOT_STARTS_WITH' | 'IS_NULL' | 'NOT_NULL';
+/** Value payload for full-text (Lucene) searches. */
+interface FullTextQuery {
+    queryText: string;
+    minScore: number | null;
+}
 /** Logical operator used to join conditions in a query. */
 type LogicalOperator = 'AND' | 'OR';
 /**
@@ -133,6 +138,7 @@ type QueryCondition = {
  */
 interface SelectQuery {
     type: 'SelectQuery';
+    table?: string | null;
     fields?: string[] | null;
     conditions?: QueryCondition | null;
     sort?: Sort[] | null;
@@ -473,6 +479,16 @@ interface IQueryBuilder<T = unknown> {
      * ```
      */
     resolve(...values: Array<string | string[]>): IQueryBuilder<T>;
+    /**
+     * Adds a Lucene full-text search predicate.
+     * @example
+     * ```ts
+     * const results = await db.from('User').search('hello world', 4.4).list();
+     * ```
+     * @param queryText - Text to match against `__full_text__`.
+     * @param minScore - Optional minimum score; serializes as `null` when omitted.
+     */
+    search(queryText: string, minScore?: number | null): IQueryBuilder<T>;
     /**
      * Adds a filter condition.
      * @example
@@ -861,6 +877,18 @@ interface IOnyxDatabase<Schema = Record<string, unknown>> {
      * @param fields Field names to project; omit to select all.
      */
     select(...fields: string[]): IQueryBuilder<Record<string, unknown>>;
+    /**
+     * Run a Lucene full-text search across all tables.
+     *
+     * @example
+     * ```ts
+     * const results = await db.search('hello world', 4.4).list();
+     * ```
+     *
+     * @param queryText Text to match against `__full_text__`.
+     * @param minScore Optional minimum score; serialized as `null` when omitted.
+     */
+    search(queryText: string, minScore?: number | null): IQueryBuilder<Record<string, unknown>>;
     /**
      * Include related records in the next save or delete.
      *
@@ -1395,6 +1423,7 @@ declare const gte: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const lt: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const lte: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const matches: (field: string, regex: string) => ConditionBuilderImpl;
+declare const search: (queryText: string, minScore?: number | null) => ConditionBuilderImpl;
 declare const notMatches: (field: string, regex: string) => ConditionBuilderImpl;
 declare const like: (field: string, pattern: string) => ConditionBuilderImpl;
 declare const notLike: (field: string, pattern: string) => ConditionBuilderImpl;
@@ -1421,4 +1450,4 @@ declare const substring: (attribute: string, from: number, length: number) => st
 declare const replace: (attribute: string, pattern: string, repl: string) => string;
 declare const percentile: (attribute: string, p: number) => string;
 
-export { within as $, type QueryCriteriaOperator as A, type Sort as B, type StreamAction as C, type OnyxDocument as D, type FetchImpl as E, type FetchResponse as F, type QueryCriteria as G, type QueryCondition as H, type IOnyxDatabase as I, type SelectQuery as J, type QueryPage as K, type LogicalOperator as L, type IConditionBuilder as M, type IQueryBuilder as N, type OnyxFacade as O, type ISaveBuilder as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type ICascadeBuilder as T, type UpdateQuery as U, type ICascadeRelationshipBuilder as V, asc as W, desc as X, eq as Y, neq as Z, inOp as _, type QueryResultsPromise as a, notIn as a0, notWithin as a1, between as a2, gt as a3, gte as a4, lt as a5, lte as a6, matches as a7, notMatches as a8, like as a9, notLike as aa, contains as ab, containsIgnoreCase as ac, notContains as ad, notContainsIgnoreCase as ae, startsWith as af, notStartsWith as ag, isNull as ah, notNull as ai, avg as aj, sum as ak, count as al, min as am, max as an, std as ao, variance as ap, median as aq, upper as ar, lower as as, substring as at, replace as au, percentile as av, type OnyxConfig as b, type SecretRecord as c, type SecretsListResponse as d, type SecretSaveRequest as e, type SchemaDataType as f, type SchemaIdentifierGenerator as g, type SchemaIdentifier as h, type SchemaAttribute as i, type SchemaIndexType as j, type SchemaIndex as k, type SchemaResolver as l, type SchemaTriggerEvent as m, type SchemaTrigger as n, type SchemaEntity as o, type SchemaRevisionMetadata as p, type SchemaRevision as q, type SchemaHistoryEntry as r, type SchemaUpsertRequest as s, type SchemaValidationResult as t, type SchemaAttributeChange as u, type SchemaIndexChange as v, type SchemaResolverChange as w, type SchemaTriggerChange as x, type SchemaTableDiff as y, type SchemaDiff as z };
+export { inOp as $, type QueryCriteriaOperator as A, type Sort as B, type StreamAction as C, type OnyxDocument as D, type FetchResponse as E, type FullTextQuery as F, type FetchImpl as G, type QueryCriteria as H, type IOnyxDatabase as I, type QueryCondition as J, type SelectQuery as K, type LogicalOperator as L, type QueryPage as M, type IConditionBuilder as N, type OnyxFacade as O, type IQueryBuilder as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type ISaveBuilder as T, type UpdateQuery as U, type ICascadeBuilder as V, type ICascadeRelationshipBuilder as W, asc as X, desc as Y, eq as Z, neq as _, type QueryResultsPromise as a, within as a0, notIn as a1, notWithin as a2, between as a3, gt as a4, gte as a5, lt as a6, lte as a7, matches as a8, search as a9, notMatches as aa, like as ab, notLike as ac, contains as ad, containsIgnoreCase as ae, notContains as af, notContainsIgnoreCase as ag, startsWith as ah, notStartsWith as ai, isNull as aj, notNull as ak, avg as al, sum as am, count as an, min as ao, max as ap, std as aq, variance as ar, median as as, upper as at, lower as au, substring as av, replace as aw, percentile as ax, type OnyxConfig as b, type SecretRecord as c, type SecretsListResponse as d, type SecretSaveRequest as e, type SchemaDataType as f, type SchemaIdentifierGenerator as g, type SchemaIdentifier as h, type SchemaAttribute as i, type SchemaIndexType as j, type SchemaIndex as k, type SchemaResolver as l, type SchemaTriggerEvent as m, type SchemaTrigger as n, type SchemaEntity as o, type SchemaRevisionMetadata as p, type SchemaRevision as q, type SchemaHistoryEntry as r, type SchemaUpsertRequest as s, type SchemaValidationResult as t, type SchemaAttributeChange as u, type SchemaIndexChange as v, type SchemaResolverChange as w, type SchemaTriggerChange as x, type SchemaTableDiff as y, type SchemaDiff as z };

package/dist/{aggregates-BGXzij4U.d.ts → aggregates-DodZNu9-.d.ts}

@@ -7,6 +7,11 @@
  * ```
  */
 type QueryCriteriaOperator = 'EQUAL' | 'NOT_EQUAL' | 'IN' | 'NOT_IN' | 'GREATER_THAN' | 'GREATER_THAN_EQUAL' | 'LESS_THAN' | 'LESS_THAN_EQUAL' | 'MATCHES' | 'NOT_MATCHES' | 'BETWEEN' | 'LIKE' | 'NOT_LIKE' | 'CONTAINS' | 'CONTAINS_IGNORE_CASE' | 'NOT_CONTAINS' | 'NOT_CONTAINS_IGNORE_CASE' | 'STARTS_WITH' | 'NOT_STARTS_WITH' | 'IS_NULL' | 'NOT_NULL';
+/** Value payload for full-text (Lucene) searches. */
+interface FullTextQuery {
+    queryText: string;
+    minScore: number | null;
+}
 /** Logical operator used to join conditions in a query. */
 type LogicalOperator = 'AND' | 'OR';
 /**
@@ -133,6 +138,7 @@ type QueryCondition = {
  */
 interface SelectQuery {
     type: 'SelectQuery';
+    table?: string | null;
     fields?: string[] | null;
     conditions?: QueryCondition | null;
     sort?: Sort[] | null;
@@ -473,6 +479,16 @@ interface IQueryBuilder<T = unknown> {
      * ```
      */
     resolve(...values: Array<string | string[]>): IQueryBuilder<T>;
+    /**
+     * Adds a Lucene full-text search predicate.
+     * @example
+     * ```ts
+     * const results = await db.from('User').search('hello world', 4.4).list();
+     * ```
+     * @param queryText - Text to match against `__full_text__`.
+     * @param minScore - Optional minimum score; serializes as `null` when omitted.
+     */
+    search(queryText: string, minScore?: number | null): IQueryBuilder<T>;
     /**
      * Adds a filter condition.
      * @example
@@ -861,6 +877,18 @@ interface IOnyxDatabase<Schema = Record<string, unknown>> {
      * @param fields Field names to project; omit to select all.
      */
     select(...fields: string[]): IQueryBuilder<Record<string, unknown>>;
+    /**
+     * Run a Lucene full-text search across all tables.
+     *
+     * @example
+     * ```ts
+     * const results = await db.search('hello world', 4.4).list();
+     * ```
+     *
+     * @param queryText Text to match against `__full_text__`.
+     * @param minScore Optional minimum score; serialized as `null` when omitted.
+     */
+    search(queryText: string, minScore?: number | null): IQueryBuilder<Record<string, unknown>>;
     /**
      * Include related records in the next save or delete.
      *
@@ -1395,6 +1423,7 @@ declare const gte: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const lt: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const lte: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const matches: (field: string, regex: string) => ConditionBuilderImpl;
+declare const search: (queryText: string, minScore?: number | null) => ConditionBuilderImpl;
 declare const notMatches: (field: string, regex: string) => ConditionBuilderImpl;
 declare const like: (field: string, pattern: string) => ConditionBuilderImpl;
 declare const notLike: (field: string, pattern: string) => ConditionBuilderImpl;
@@ -1421,4 +1450,4 @@ declare const substring: (attribute: string, from: number, length: number) => st
 declare const replace: (attribute: string, pattern: string, repl: string) => string;
 declare const percentile: (attribute: string, p: number) => string;
 
-export { within as $, type QueryCriteriaOperator as A, type Sort as B, type StreamAction as C, type OnyxDocument as D, type FetchImpl as E, type FetchResponse as F, type QueryCriteria as G, type QueryCondition as H, type IOnyxDatabase as I, type SelectQuery as J, type QueryPage as K, type LogicalOperator as L, type IConditionBuilder as M, type IQueryBuilder as N, type OnyxFacade as O, type ISaveBuilder as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type ICascadeBuilder as T, type UpdateQuery as U, type ICascadeRelationshipBuilder as V, asc as W, desc as X, eq as Y, neq as Z, inOp as _, type QueryResultsPromise as a, notIn as a0, notWithin as a1, between as a2, gt as a3, gte as a4, lt as a5, lte as a6, matches as a7, notMatches as a8, like as a9, notLike as aa, contains as ab, containsIgnoreCase as ac, notContains as ad, notContainsIgnoreCase as ae, startsWith as af, notStartsWith as ag, isNull as ah, notNull as ai, avg as aj, sum as ak, count as al, min as am, max as an, std as ao, variance as ap, median as aq, upper as ar, lower as as, substring as at, replace as au, percentile as av, type OnyxConfig as b, type SecretRecord as c, type SecretsListResponse as d, type SecretSaveRequest as e, type SchemaDataType as f, type SchemaIdentifierGenerator as g, type SchemaIdentifier as h, type SchemaAttribute as i, type SchemaIndexType as j, type SchemaIndex as k, type SchemaResolver as l, type SchemaTriggerEvent as m, type SchemaTrigger as n, type SchemaEntity as o, type SchemaRevisionMetadata as p, type SchemaRevision as q, type SchemaHistoryEntry as r, type SchemaUpsertRequest as s, type SchemaValidationResult as t, type SchemaAttributeChange as u, type SchemaIndexChange as v, type SchemaResolverChange as w, type SchemaTriggerChange as x, type SchemaTableDiff as y, type SchemaDiff as z };
+export { inOp as $, type QueryCriteriaOperator as A, type Sort as B, type StreamAction as C, type OnyxDocument as D, type FetchResponse as E, type FullTextQuery as F, type FetchImpl as G, type QueryCriteria as H, type IOnyxDatabase as I, type QueryCondition as J, type SelectQuery as K, type LogicalOperator as L, type QueryPage as M, type IConditionBuilder as N, type OnyxFacade as O, type IQueryBuilder as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type ISaveBuilder as T, type UpdateQuery as U, type ICascadeBuilder as V, type ICascadeRelationshipBuilder as W, asc as X, desc as Y, eq as Z, neq as _, type QueryResultsPromise as a, within as a0, notIn as a1, notWithin as a2, between as a3, gt as a4, gte as a5, lt as a6, lte as a7, matches as a8, search as a9, notMatches as aa, like as ab, notLike as ac, contains as ad, containsIgnoreCase as ae, notContains as af, notContainsIgnoreCase as ag, startsWith as ah, notStartsWith as ai, isNull as aj, notNull as ak, avg as al, sum as am, count as an, min as ao, max as ap, std as aq, variance as ar, median as as, upper as at, lower as au, substring as av, replace as aw, percentile as ax, type OnyxConfig as b, type SecretRecord as c, type SecretsListResponse as d, type SecretSaveRequest as e, type SchemaDataType as f, type SchemaIdentifierGenerator as g, type SchemaIdentifier as h, type SchemaAttribute as i, type SchemaIndexType as j, type SchemaIndex as k, type SchemaResolver as l, type SchemaTriggerEvent as m, type SchemaTrigger as n, type SchemaEntity as o, type SchemaRevisionMetadata as p, type SchemaRevision as q, type SchemaHistoryEntry as r, type SchemaUpsertRequest as s, type SchemaValidationResult as t, type SchemaAttributeChange as u, type SchemaIndexChange as v, type SchemaResolverChange as w, type SchemaTriggerChange as x, type SchemaTableDiff as y, type SchemaDiff as z };

package/dist/edge.cjs

@@ -1179,6 +1179,14 @@ var OnyxDatabaseImpl = class {
     qb.select(...fields);
     return qb;
   }
+  search(queryText, minScore) {
+    const qb = new QueryBuilderImpl(
+      this,
+      "ALL",
+      this.defaultPartition
+    );
+    return qb.search(queryText, minScore);
+  }
   cascade(...relationships) {
     const cb = new CascadeBuilderImpl(this);
     return cb.cascade(...relationships);
@@ -1465,6 +1473,7 @@ var QueryBuilderImpl = class {
   toSelectQuery() {
     return {
       type: "SelectQuery",
+      table: this.table,
       fields: this.fields,
       conditions: this.serializableConditions(),
       sort: this.sort,
@@ -1504,6 +1513,13 @@ var QueryBuilderImpl = class {
     this.resolvers = flat.length > 0 ? flat : null;
     return this;
   }
+  search(queryText, minScore) {
+    return this.and({
+      field: "__full_text__",
+      operator: "MATCHES",
+      value: { queryText, minScore: minScore ?? null }
+    });
+  }
   where(condition) {
     const c2 = toCondition(condition);
     if (!this.conditions) {
@@ -1855,6 +1871,10 @@ var ConditionBuilderImpl = class {
 
 // src/helpers/conditions.ts
 var c = (field, operator, value) => new ConditionBuilderImpl({ field, operator, value });
+var fullText = (queryText, minScore) => ({
+  queryText,
+  minScore: minScore ?? null
+});
 var eq = (field, value) => c(field, "EQUAL", value);
 var neq = (field, value) => c(field, "NOT_EQUAL", value);
 function inOp(field, values) {
@@ -1877,6 +1897,7 @@ var gte = (field, value) => c(field, "GREATER_THAN_EQUAL", value);
 var lt = (field, value) => c(field, "LESS_THAN", value);
 var lte = (field, value) => c(field, "LESS_THAN_EQUAL", value);
 var matches = (field, regex) => c(field, "MATCHES", regex);
+var search = (queryText, minScore) => c("__full_text__", "MATCHES", fullText(queryText, minScore));
 var notMatches = (field, regex) => c(field, "NOT_MATCHES", regex);
 var like = (field, pattern) => c(field, "LIKE", pattern);
 var notLike = (field, pattern) => c(field, "NOT_LIKE", pattern);
@@ -1943,6 +1964,7 @@ exports.percentile = percentile;
 exports.replace = replace;
 exports.sdkName = sdkName;
 exports.sdkVersion = sdkVersion;
+exports.search = search;
 exports.startsWith = startsWith;
 exports.std = std;
 exports.substring = substring;