@onyx.dev/onyx-database 1.0.2 → 1.1.0

package/README.md

@@ -13,6 +13,26 @@ TypeScript client SDK for **Onyx Cloud Database** — a zero-dependency, strict-
 
 ---
 
+## Table of contents
+
+- [Getting started](#getting-started-cloud--keys--connect)
+- [Install](#install)
+- [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)
+- [Onyx CLI](#onyx-cli)
+- [Runtime & bundlers](#runtime--bundlers)
+- [Release workflow](#release-workflow)
+- [Related links](#related-links)
+- [Security](#security)
+- [License](#license)
+
+---
+
 ## Getting started (Cloud ➜ keys ➜ connect)
 
 1. **Sign up & create resources** at **<https://cloud.onyx.dev>**  
@@ -116,6 +136,37 @@ Set `ONYX_CONFIG_PATH` to a JSON file containing your credentials. This file is
 
 These files are ignored in non-Node runtimes like Cloudflare Workers.
 
+### Edge / RSC usage (Next.js, Cloudflare Workers)
+
+For edge runtimes (Next.js Edge/RSC, Cloudflare Workers), import the edge entry. It avoids Node-only imports and only resolves credentials from environment variables or explicit config.
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database/edge';
+
+const db = onyx.init(); // uses env vars in edge runtimes
+```
+
+File-based config (`ONYX_CONFIG_PATH`, project files, home profiles) is not available in edge runtimes. If you need file-based config, use the Node entry instead.
+
+**Cloudflare Worker example:**
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database/edge';
+
+export default {
+  async fetch(_request: Request, env: Record<string, string>) {
+    const db = onyx.init({
+      baseUrl: env.ONYX_DATABASE_BASE_URL,
+      databaseId: env.ONYX_DATABASE_ID,
+      apiKey: env.ONYX_DATABASE_API_KEY,
+      apiSecret: env.ONYX_DATABASE_API_SECRET,
+    });
+
+    return Response.json({ ok: true });
+  },
+};
+```
+
 ### Connection handling
 
 Calling `onyx.init()` returns a lightweight client. Configuration is resolved once
@@ -360,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';
@@ -368,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)
 
@@ -403,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`.  
@@ -665,7 +747,60 @@ try {
 }
 ```
 
----
+## HTTP retries
+
+- GET requests retry automatically with Fibonacci backoff (300ms base) up to 3 times by default; mutations are never retried.
+- Disable or tune via `retry` on `onyx.init`:
+
+```ts
+const db = onyx.init({
+  retry: {
+    enabled: true,     // default
+    maxRetries: 2,     // default 3
+    initialDelayMs: 500, // default 300
+  },
+});
+```
+
+## Onyx CLI
+
+
+```
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| Command              | Flags                                         | Defaults / notes                                             |
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| onyx-gen             | --source auto|api|file                        | Default: --source file; --schema ./onyx.schema.json;         |
+|                      | --schema <path>                               | --out ./onyx/types.ts (file or dir; repeatable; dir uses     |
+|                      | --out / --types-out / --types-file <dir|file> | --base onyx.schema); timestamps default: date; optional      |
+|                      | --base / --baseName <name>                    | strategy default: non-null; schema type name: OnyxSchema;    |
+|                      | --timestamps string|date|number               | emit-json disabled by default; --overwrite enabled; quiet=false. |
+|                      | --name / --schemaTypeName <T>                 | --api-path repeatable; --json-out derived from TS output.    |
+|                      | --prefix <Prefix>                             |                                                              |
+|                      | --optional non-null|nullable|none             |                                                              |
+|                      | --emit-json / --no-emit-json                  |                                                              |
+|                      | --json-out <dir>                              |                                                              |
+|                      | --api-path <path> (repeatable)                |                                                              |
+|                      | --overwrite / --no-overwrite                  |                                                              |
+|                      | -q / --quiet                                  |                                                              |
+|                      | -h / --help                                   |                                                              |
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| onyx-schema get      | [file] (positional)                           | Default file: ./onyx.schema.json; writes file unless         |
+|                      | --tables a,b                                  | --tables or --print (then prints to stdout).                 |
+|                      | --print                                       |                                                              |
+|                      | -h / --help                                   |                                                              |
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| onyx-schema publish  | [file] (positional)                           | Default file: ./onyx.schema.json; validates before publishing; |
+|                      | -h / --help                                   | uses onyx.init credential resolver.                          |
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| onyx-schema validate | [file] (positional)                           | Default file: ./onyx.schema.json; exits non-zero on errors.  |
+|                      | -h / --help                                   |                                                              |
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| onyx-schema diff     | [file] (positional)                           | Default file: ./onyx.schema.json; prints YAML diff vs API.   |
+|                      | -h / --help                                   |                                                              |
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+| onyx-schema info     | -h / --help                                   | Shows resolved config sources, config path, connection check.|
++----------------------+-----------------------------------------------+--------------------------------------------------------------+
+```
 
 ## Runtime & bundlers