@onyx.dev/onyx-database 0.3.0 → 1.0.2

package/README.md

@@ -42,6 +42,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
@@ -148,6 +164,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
 
@@ -174,6 +193,10 @@ onyx-schema get --tables=User,Profile
 
 # Validate a schema file without publishing
 onyx-schema validate ./onyx.schema.json
+
+# Diff local schema vs API
+onyx-schema diff ./onyx.schema.json
+# 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
@@ -190,6 +213,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
@@ -322,7 +355,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,
@@ -331,6 +366,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`

package/dist/gen/cli/generate.cjs

@@ -76,7 +76,7 @@ function readEnv(targetId) {
   return res;
 }
 async function readProjectFile(databaseId) {
-  if (!isNode) return {};
+  if (!isNode) return { config: {} };
   const fs = await nodeImport("node:fs/promises");
   const path = await nodeImport("node:path");
   const cwd = gProcess?.cwd?.() ?? ".";
@@ -85,7 +85,7 @@ async function readProjectFile(databaseId) {
     const sanitized = txt.replace(/[\r\n]+/g, "");
     const json = dropUndefined(JSON.parse(sanitized));
     dbg("project file:", p, "\u2192", mask(json));
-    return json;
+    return { config: json, path: p };
   };
   if (databaseId) {
     const specific = path.resolve(cwd, `onyx-database-${databaseId}.json`);
@@ -100,11 +100,11 @@ async function readProjectFile(databaseId) {
     return await tryRead(fallback);
   } catch {
     dbg("project file not found:", fallback);
-    return {};
+    return { config: {} };
   }
 }
 async function readHomeProfile(databaseId) {
-  if (!isNode) return {};
+  if (!isNode) return { config: {} };
   const fs = await nodeImport("node:fs/promises");
   const os = await nodeImport("node:os");
   const path = await nodeImport("node:path");
@@ -124,7 +124,7 @@ async function readHomeProfile(databaseId) {
       const sanitized = txt.replace(/[\r\n]+/g, "");
       const json = dropUndefined(JSON.parse(sanitized));
       dbg("home profile used:", p, "\u2192", mask(json));
-      return json;
+      return { config: json, path: p };
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       throw new OnyxConfigError(`Failed to read ${p}: ${msg}`);
@@ -143,7 +143,7 @@ async function readHomeProfile(databaseId) {
   dbg("no home-root fallback:", defaultInHome);
   if (!await fileExists(dir)) {
     dbg("~/.onyx does not exist:", dir);
-    return {};
+    return { config: {} };
   }
   const files = await fs.readdir(dir).catch(() => []);
   const matches = files.filter((f) => f.startsWith("onyx-database-") && f.endsWith(".json"));
@@ -157,10 +157,10 @@ async function readHomeProfile(databaseId) {
     );
   }
   dbg("no usable home profiles found in", dir);
-  return {};
+  return { config: {} };
 }
 async function readConfigPath(p) {
-  if (!isNode) return {};
+  if (!isNode) return { config: {} };
   const fs = await nodeImport("node:fs/promises");
   const path = await nodeImport("node:path");
   const cwd = gProcess?.cwd?.() ?? ".";
@@ -170,7 +170,7 @@ async function readConfigPath(p) {
     const sanitized = txt.replace(/[\r\n]+/g, "");
     const json = dropUndefined(JSON.parse(sanitized));
     dbg("config path:", resolved, "\u2192", mask(json));
-    return json;
+    return { config: json, path: resolved };
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     throw new OnyxConfigError(`Failed to read ${resolved}: ${msg}`);
@@ -181,7 +181,8 @@ async function resolveConfig(input) {
   const env = readEnv(input?.databaseId);
   let cfgPath = {};
   if (configPath) {
-    cfgPath = await readConfigPath(configPath);
+    const cfgRes = await readConfigPath(configPath);
+    cfgPath = cfgRes.config;
   }
   const targetId = input?.databaseId ?? env.databaseId ?? cfgPath.databaseId;
   let haveDbId = !!(input?.databaseId ?? env.databaseId ?? cfgPath.databaseId);
@@ -189,14 +190,16 @@ async function resolveConfig(input) {
   let haveApiSecret = !!(input?.apiSecret ?? env.apiSecret ?? cfgPath.apiSecret);
   let project = {};
   if (!(haveDbId && haveApiKey && haveApiSecret)) {
-    project = await readProjectFile(targetId);
+    const projRes = await readProjectFile(targetId);
+    project = projRes.config;
     if (project.databaseId) haveDbId = true;
     if (project.apiKey) haveApiKey = true;
     if (project.apiSecret) haveApiSecret = true;
   }
   let home = {};
   if (!(haveDbId && haveApiKey && haveApiSecret)) {
-    home = await readHomeProfile(targetId);
+    const homeRes = await readHomeProfile(targetId);
+    home = homeRes.config;
   }
   const merged = {
     baseUrl: DEFAULT_BASE_URL,
@@ -931,6 +934,56 @@ var QueryResults = class extends Array {
   }
 };
 
+// src/helpers/condition-normalizer.ts
+function isQueryBuilderLike(value) {
+  return !!value && typeof value.toSerializableQueryObject === "function";
+}
+function normalizeCriteriaValue(value) {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const normalized = value.map((item) => {
+      const result = normalizeCriteriaValue(item);
+      if (result.changed) changed = true;
+      return result.value;
+    });
+    if (!changed) {
+      for (let i = 0; i < normalized.length; i += 1) {
+        if (normalized[i] !== value[i]) {
+          changed = true;
+          break;
+        }
+      }
+    }
+    return { value: changed ? normalized : value, changed };
+  }
+  if (isQueryBuilderLike(value)) {
+    return { value: value.toSerializableQueryObject(), changed: true };
+  }
+  return { value, changed: false };
+}
+function normalizeConditionInternal(condition) {
+  if (condition.conditionType === "SingleCondition") {
+    const { value, changed: changed2 } = normalizeCriteriaValue(condition.criteria.value);
+    if (!changed2) return condition;
+    return {
+      ...condition,
+      criteria: { ...condition.criteria, value }
+    };
+  }
+  let changed = false;
+  const normalizedConditions = condition.conditions.map((child) => {
+    const normalized = normalizeConditionInternal(child);
+    if (normalized !== child) changed = true;
+    return normalized;
+  });
+  if (!changed) return condition;
+  return { ...condition, conditions: normalizedConditions };
+}
+function normalizeCondition(condition) {
+  if (!condition) return condition;
+  return normalizeConditionInternal(condition);
+}
+
 // src/builders/cascade-relationship-builder.ts
 var CascadeRelationshipBuilder = class {
   graphName;
@@ -1005,6 +1058,194 @@ var OnyxError = class extends Error {
   }
 };
 
+// src/helpers/schema-diff.ts
+function mapByName(items) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items ?? []) {
+    if (!item?.name) continue;
+    map.set(item.name, item);
+  }
+  return map;
+}
+function normalizeEntities(schema) {
+  if (Array.isArray(schema.entities)) {
+    return schema.entities ?? [];
+  }
+  const tables = schema.tables;
+  if (!Array.isArray(tables)) return [];
+  return tables.map((table) => ({
+    name: table.name,
+    attributes: table.attributes ?? []
+  }));
+}
+function normalizePartition(partition) {
+  if (partition == null) return "";
+  const trimmed = partition.trim();
+  return trimmed;
+}
+function identifiersEqual(a, b) {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return a.name === b.name && a.generator === b.generator && a.type === b.type;
+}
+function diffAttributes(apiAttrs, localAttrs) {
+  const apiMap = mapByName(apiAttrs);
+  const localMap = mapByName(localAttrs);
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [name, local] of localMap.entries()) {
+    if (!apiMap.has(name)) {
+      added.push(local);
+      continue;
+    }
+    const api = apiMap.get(name);
+    const apiNull = Boolean(api.isNullable);
+    const localNull = Boolean(local.isNullable);
+    if (api.type !== local.type || apiNull !== localNull) {
+      changed.push({
+        name,
+        from: { type: api.type, isNullable: apiNull },
+        to: { type: local.type, isNullable: localNull }
+      });
+    }
+  }
+  for (const name of apiMap.keys()) {
+    if (!localMap.has(name)) removed.push(name);
+  }
+  added.sort((a, b) => a.name.localeCompare(b.name));
+  removed.sort();
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+  if (!added.length && !removed.length && !changed.length) return null;
+  return { added, removed, changed };
+}
+function diffIndexes(apiIndexes, localIndexes) {
+  const apiMap = mapByName(apiIndexes);
+  const localMap = mapByName(localIndexes);
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [name, local] of localMap.entries()) {
+    if (!apiMap.has(name)) {
+      added.push(local);
+      continue;
+    }
+    const api = apiMap.get(name);
+    const apiType = api.type ?? "DEFAULT";
+    const localType = local.type ?? "DEFAULT";
+    const apiScore = api.minimumScore;
+    const localScore = local.minimumScore;
+    if (apiType !== localType || apiScore !== localScore) {
+      changed.push({ name, from: api, to: local });
+    }
+  }
+  for (const name of apiMap.keys()) {
+    if (!localMap.has(name)) removed.push(name);
+  }
+  added.sort((a, b) => a.name.localeCompare(b.name));
+  removed.sort();
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+  if (!added.length && !removed.length && !changed.length) return null;
+  return { added, removed, changed };
+}
+function diffResolvers(apiResolvers, localResolvers) {
+  const apiMap = mapByName(apiResolvers);
+  const localMap = mapByName(localResolvers);
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [name, local] of localMap.entries()) {
+    if (!apiMap.has(name)) {
+      added.push(local);
+      continue;
+    }
+    const api = apiMap.get(name);
+    if (api.resolver !== local.resolver) {
+      changed.push({ name, from: api, to: local });
+    }
+  }
+  for (const name of apiMap.keys()) {
+    if (!localMap.has(name)) removed.push(name);
+  }
+  added.sort((a, b) => a.name.localeCompare(b.name));
+  removed.sort();
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+  if (!added.length && !removed.length && !changed.length) return null;
+  return { added, removed, changed };
+}
+function diffTriggers(apiTriggers, localTriggers) {
+  const apiMap = mapByName(apiTriggers);
+  const localMap = mapByName(localTriggers);
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [name, local] of localMap.entries()) {
+    if (!apiMap.has(name)) {
+      added.push(local);
+      continue;
+    }
+    const api = apiMap.get(name);
+    if (api.event !== local.event || api.trigger !== local.trigger) {
+      changed.push({ name, from: api, to: local });
+    }
+  }
+  for (const name of apiMap.keys()) {
+    if (!localMap.has(name)) removed.push(name);
+  }
+  added.sort((a, b) => a.name.localeCompare(b.name));
+  removed.sort();
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+  if (!added.length && !removed.length && !changed.length) return null;
+  return { added, removed, changed };
+}
+function computeSchemaDiff(apiSchema, localSchema) {
+  const apiEntities = normalizeEntities(apiSchema);
+  const localEntities = normalizeEntities(localSchema);
+  const apiMap = mapByName(apiEntities);
+  const localMap = mapByName(localEntities);
+  const newTables = [];
+  const removedTables = [];
+  const changedTables = [];
+  for (const [name, localEntity] of localMap.entries()) {
+    if (!apiMap.has(name)) {
+      newTables.push(name);
+      continue;
+    }
+    const apiEntity = apiMap.get(name);
+    const tableDiff = { name };
+    const partitionFrom = normalizePartition(apiEntity.partition);
+    const partitionTo = normalizePartition(localEntity.partition);
+    if (partitionFrom !== partitionTo) {
+      tableDiff.partition = { from: partitionFrom || null, to: partitionTo || null };
+    }
+    if (!identifiersEqual(apiEntity.identifier, localEntity.identifier)) {
+      tableDiff.identifier = {
+        from: apiEntity.identifier ?? null,
+        to: localEntity.identifier ?? null
+      };
+    }
+    const attrs = diffAttributes(apiEntity.attributes, localEntity.attributes);
+    if (attrs) tableDiff.attributes = attrs;
+    const indexes = diffIndexes(apiEntity.indexes, localEntity.indexes);
+    if (indexes) tableDiff.indexes = indexes;
+    const resolvers = diffResolvers(apiEntity.resolvers, localEntity.resolvers);
+    if (resolvers) tableDiff.resolvers = resolvers;
+    const triggers = diffTriggers(apiEntity.triggers, localEntity.triggers);
+    if (triggers) tableDiff.triggers = triggers;
+    const hasChange = tableDiff.partition || tableDiff.identifier || tableDiff.attributes || tableDiff.indexes || tableDiff.resolvers || tableDiff.triggers;
+    if (hasChange) {
+      changedTables.push(tableDiff);
+    }
+  }
+  for (const name of apiMap.keys()) {
+    if (!localMap.has(name)) removedTables.push(name);
+  }
+  newTables.sort();
+  removedTables.sort();
+  changedTables.sort((a, b) => a.name.localeCompare(b.name));
+  return { newTables, removedTables, changedTables };
+}
+
 // src/impl/onyx.ts
 var DEFAULT_CACHE_TTL = 5 * 60 * 1e3;
 var cachedCfg = null;
@@ -1058,6 +1299,10 @@ function serializeDates(value) {
   }
   return value;
 }
+function stripEntityText(input) {
+  const { entityText, ...rest } = input;
+  return rest;
+}
 function normalizeSecretMetadata(input) {
   return { ...input, updatedAt: new Date(input.updatedAt) };
 }
@@ -1071,7 +1316,20 @@ function normalizeDate(value) {
   return Number.isNaN(ts.getTime()) ? void 0 : ts;
 }
 function normalizeSchemaRevision(input, fallbackDatabaseId) {
-  const { meta, createdAt, publishedAt, revisionId, ...rest } = input;
+  const {
+    meta,
+    createdAt,
+    publishedAt,
+    revisionId,
+    entityText,
+    databaseId,
+    entities,
+    revisionDescription,
+    ...rest
+  } = input;
+  const dbId = typeof databaseId === "string" ? databaseId : fallbackDatabaseId;
+  const entityList = Array.isArray(entities) ? entities : [];
+  const revisionDesc = typeof revisionDescription === "string" ? revisionDescription : void 0;
   const mergedMeta = {
     revisionId: meta?.revisionId ?? revisionId,
     createdAt: normalizeDate(meta?.createdAt ?? createdAt),
@@ -1079,10 +1337,11 @@ function normalizeSchemaRevision(input, fallbackDatabaseId) {
   };
   const cleanedMeta = mergedMeta.revisionId || mergedMeta.createdAt || mergedMeta.publishedAt ? mergedMeta : void 0;
   return {
-    ...rest,
-    databaseId: input.databaseId ?? fallbackDatabaseId,
+    databaseId: dbId,
+    revisionDescription: revisionDesc,
+    entities: entityList,
     meta: cleanedMeta,
-    entities: input.entities ?? []
+    ...rest
   };
 }
 var OnyxDatabaseImpl = class {
@@ -1194,7 +1453,8 @@ var OnyxDatabaseImpl = class {
     const path = `/data/${encodeURIComponent(databaseId)}/${encodeURIComponent(
       table
     )}/${encodeURIComponent(primaryKey)}${params.toString() ? `?${params.toString()}` : ""}`;
-    return http.request("DELETE", path);
+    await http.request("DELETE", path);
+    return true;
   }
   async saveDocument(doc) {
     const { http, databaseId } = await this.ensureClient();
@@ -1237,20 +1497,32 @@ var OnyxDatabaseImpl = class {
     const res = await http.request("GET", path);
     return Array.isArray(res) ? res.map((entry) => normalizeSchemaRevision(entry, databaseId)) : [];
   }
+  async diffSchema(localSchema) {
+    const apiSchema = await this.getSchema();
+    return computeSchemaDiff(apiSchema, localSchema);
+  }
   async updateSchema(schema, options) {
     const { http, databaseId } = await this.ensureClient();
     const params = new URLSearchParams();
     if (options?.publish) params.append("publish", "true");
     const path = `/schemas/${encodeURIComponent(databaseId)}${params.size ? `?${params.toString()}` : ""}`;
-    const body = { ...schema, databaseId: schema.databaseId ?? databaseId };
-    const res = await http.request("PUT", path, serializeDates(body));
+    const body = stripEntityText({ ...schema, databaseId: schema.databaseId ?? databaseId });
+    const res = await http.request(
+      "PUT",
+      path,
+      serializeDates(body)
+    );
     return normalizeSchemaRevision(res, databaseId);
   }
   async validateSchema(schema) {
     const { http, databaseId } = await this.ensureClient();
     const path = `/schemas/${encodeURIComponent(databaseId)}/validate`;
-    const body = { ...schema, databaseId: schema.databaseId ?? databaseId };
-    const res = await http.request("POST", path, serializeDates(body));
+    const body = stripEntityText({ ...schema, databaseId: schema.databaseId ?? databaseId });
+    const res = await http.request(
+      "POST",
+      path,
+      serializeDates(body)
+    );
     const normalizedSchema = res.schema ? normalizeSchemaRevision(res.schema, databaseId) : void 0;
     return {
       ...res,
@@ -1412,11 +1684,14 @@ var QueryBuilderImpl = class {
     if (!this.table) throw new Error("Table is not defined. Call from(<table>) first.");
     return this.table;
   }
+  serializableConditions() {
+    return normalizeCondition(this.conditions);
+  }
   toSelectQuery() {
     return {
       type: "SelectQuery",
       fields: this.fields,
-      conditions: this.conditions,
+      conditions: this.serializableConditions(),
       sort: this.sort,
       limit: this.limitValue,
       distinct: this.distinctValue,
@@ -1425,6 +1700,21 @@ var QueryBuilderImpl = class {
       resolvers: this.resolvers
     };
   }
+  toUpdateQuery() {
+    return {
+      type: "UpdateQuery",
+      conditions: this.serializableConditions(),
+      updates: this.updates ?? {},
+      sort: this.sort,
+      limit: this.limitValue,
+      partition: this.partitionValue ?? null
+    };
+  }
+  toSerializableQueryObject() {
+    const table = this.ensureTable();
+    const payload = this.mode === "update" ? this.toUpdateQuery() : this.toSelectQuery();
+    return { ...payload, table };
+  }
   from(table) {
     this.table = table;
     return this;
@@ -1560,14 +1850,7 @@ var QueryBuilderImpl = class {
   async update() {
     if (this.mode !== "update") throw new Error("Call setUpdates(...) before update().");
     const table = this.ensureTable();
-    const update = {
-      type: "UpdateQuery",
-      conditions: this.conditions,
-      updates: this.updates ?? {},
-      sort: this.sort,
-      limit: this.limitValue,
-      partition: this.partitionValue ?? null
-    };
+    const update = this.toUpdateQuery();
     return this.db._update(table, update, this.partitionValue);
   }
   onItemAdded(listener) {