@onyx.dev/onyx-database 1.0.0 → 1.0.3

package/README.md

@@ -13,6 +13,25 @@ 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)
+- [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>**  
@@ -42,6 +61,22 @@ npm i @onyx.dev/onyx-database
 
 The package is dual-module (ESM + CJS) and has **no runtime or peer dependencies**.
 
+To use the bundled CLIs (`onyx-gen` and `onyx-schema`) globally:
+
+```bash
+npm install -g @onyx.dev/onyx-database
+```
+
+To install the CLI globally from this repo checkout (useful for local development and testing):
+
+```bash
+# run from the repo root
+npm install
+npm run build
+npm uninstall -g @onyx.dev/onyx-database # optional: clear older global versions
+npm install -g .                         # installs the built onyx-schema and onyx-gen
+```
+
 ---
 
 ## Initialize the client
@@ -100,6 +135,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
@@ -148,6 +214,9 @@ onyx-schema publish
 # Overwrite ./onyx.schema.json with the remote schema
 onyx-schema get
 
+# Print the remote schema without writing a file
+onyx-schema get --print
+
 # Fetch only selected tables (prints to stdout; does not overwrite files)
 onyx-schema get --tables=User,Profile
 
@@ -177,7 +246,7 @@ onyx-schema validate ./onyx.schema.json
 
 # Diff local schema vs API
 onyx-schema diff ./onyx.schema.json
-# Prints added/removed/changed tables and attribute differences between the API schema and your local file.
+# Prints YAML with added/removed/changed tables and attribute differences between the API schema and your local file.
 ```
 
 When `--tables` is provided, the subset is printed to stdout instead of writing a
@@ -194,6 +263,16 @@ npm run schema:publish   # validate then publish the local schema
 The CLI reuses the same configuration resolution as `onyx.init()` (env vars,
 project config, and home profile files).
 
+Programmatic diffing is also available:
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database';
+
+const db = onyx.init();
+const diff = await db.diffSchema(localSchema); // SchemaUpsertRequest
+console.log(diff.changedTables);
+```
+
 You can also emit to multiple paths in one run (comma-separated or by repeating `--out`):
 
 ```bash
@@ -636,7 +715,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