@onyx.dev/onyx-database 0.2.10 → 1.0.0

package/README.md

@@ -122,6 +122,9 @@ Generate directly from the API (using the same credential resolver as `init()`):
 npx onyx-gen --source api --out ./src/onyx/types.ts --name OnyxSchema
 ```
 
+With `--source api`, `onyx-gen` calls the Schema API (same as `onyx-schema get`) using the
+standard config chain (env, project file, home profile).
+
 Timestamp attributes are emitted as `Date` fields by default. When saving,
 `Date` values are automatically serialized to ISO timestamp strings. Pass
 `--timestamps string` to keep timestamps as ISO strings in generated types.
@@ -134,6 +137,63 @@ npx onyx-gen --source file --schema ./onyx.schema.json --out ./src/onyx/types.ts
 
 Run it with no flags to use the defaults: `onyx-gen` reads `./onyx.schema.json` and writes to `./onyx/types.ts`.
 
+### Manage schemas from the CLI
+
+Publish or download schema JSON directly via API using the `onyx-schema` helper:
+
+```bash
+# Publish ./onyx.schema.json with publish=true by default
+onyx-schema publish
+
+# Overwrite ./onyx.schema.json with the remote schema
+onyx-schema get
+
+# Fetch only selected tables (prints to stdout; does not overwrite files)
+onyx-schema get --tables=User,Profile
+
+# Example subset output
+onyx-schema get --tables=User,Profile
+# {
+#   "tables": [
+#     {
+#       "name": "User",
+#       "attributes": [
+#         { "name": "id", "type": "string", "required": true },
+#         { "name": "email", "type": "string", "required": true }
+#       ]
+#     },
+#     {
+#       "name": "Profile",
+#       "attributes": [
+#         { "name": "id", "type": "string", "required": true },
+#         { "name": "userId", "type": "string", "required": true }
+#       ]
+#     }
+#   ]
+# }
+
+# Validate a schema file without publishing
+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.
+```
+
+When `--tables` is provided, the subset is printed to stdout instead of writing a
+file. Otherwise, the CLI writes to `./onyx.schema.json` by default.
+
+In this repo's `examples/` workspace, the following scripts wrap the same commands:
+
+```bash
+npm run schema:get       # fetch remote schema into ./onyx.schema.json
+npm run schema:validate  # validate the local schema file
+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).
+
 You can also emit to multiple paths in one run (comma-separated or by repeating `--out`):
 
 ```bash
@@ -266,7 +326,9 @@ Importable helpers for conditions and sort:
 
 ```ts
 import {
-  eq, neq, inOp, notIn, between,
+  eq, neq, within, notWithin, // preferred aliases for IN/NOT IN
+  inOp, notIn,           
+  between,
   gt, gte, lt, lte,
   like, notLike, contains, notContains,
   startsWith, notStartsWith, matches, notMatches,
@@ -275,6 +337,41 @@ import {
 } from '@onyx.dev/onyx-database';
 ```
 
+- 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.
+
+### Inner queries (IN/NOT IN with sub-selects)
+
+You can pass another query builder to `within` or `notWithin` to create nested filters. The SDK serializes the inner query (including its table) before sending the request.
+
+```ts
+import { onyx, within, notWithin, eq, tables, Schema } from '@onyx.dev/onyx-database';
+
+const db = onyx.init<Schema>();
+
+// Users that HAVE the admin role
+const usersWithAdmin = await db
+  .from(tables.User)
+  .where(
+    within(
+      'id',
+      db.select('userId').from(tables.UserRole).where(eq('roleId', 'role-admin')),
+    ),
+  )
+  .list();
+
+// Roles that DO NOT include a specific permission
+const rolesMissingPermission = await db
+  .from(tables.Role)
+  .where(
+    notWithin(
+      'id',
+      db.from(tables.RolePermission).where(eq('permissionId', 'perm-manage-users')),
+    ),
+  )
+  .list();
+```
+
 ---
 
 ## Usage examples with `User`, `Role`, `Permission`
@@ -406,7 +503,75 @@ const delCount = await db
 
 ```
 
-### 5) Documents API (binary assets)
+### 5) Schema API
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database';
+const db = onyx.init();
+
+// Fetch current schema (optionally filter by tables)
+const schema = await db.getSchema({ tables: ['User', 'Profile'] });
+
+// Review history
+const history = await db.getSchemaHistory();
+
+// Validate changes without applying
+await db.validateSchema({
+  revisionDescription: 'Add profile triggers',
+  entities: [
+    {
+      name: 'Profile',
+      identifier: { name: 'id', generator: 'UUID' },
+      attributes: [
+        { name: 'id', type: 'String', isNullable: false },
+        { name: 'userId', type: 'String', isNullable: false },
+      ],
+    },
+  ],
+});
+
+// Update and optionally publish
+await db.updateSchema(
+  {
+    revisionDescription: 'Publish profile changes',
+    entities: [
+      {
+        name: 'Profile',
+        identifier: { name: 'id', generator: 'UUID' },
+        attributes: [
+          { name: 'id', type: 'String', isNullable: false },
+          { name: 'userId', type: 'String', isNullable: false },
+        ],
+      },
+    ],
+  },
+  { publish: true },
+);
+```
+
+### 6) Secrets API
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database';
+const db = onyx.init();
+
+// List secret metadata
+const list = await db.listSecrets();
+
+// Read a decrypted secret value
+const secret = await db.getSecret('api-key');
+
+// Create or update a secret
+await db.putSecret('api-key', {
+  value: 'super-secret',
+  purpose: 'Access to external API',
+});
+
+// Delete a secret
+await db.deleteSecret('api-key');
+```
+
+### 7) Documents API (binary assets)
 
 ```ts
 import { onyx, type OnyxDocument } from '@onyx.dev/onyx-database';
@@ -429,7 +594,7 @@ const image = await db.getDocument('logo.png', { width: 128, height: 128 });
 await db.deleteDocument('logo.png');
 ```
 
-### 6) Streaming (live changes)
+### 8) Streaming (live changes)
 
 ```ts
 import { onyx, eq } from '@onyx.dev/onyx-database';