@ultimat3/entity 25.2.0 → 26.0.0

package/README.md

@@ -263,7 +263,7 @@ export const accounts = entity('account', {
 
 | Override | What follows it |
 |---|---|
-| `entity(name, { table })` | every statement, index name and foreign key. The entity NAME stays the framework's key — the registry, the cache tag (`entity:account`), `x entities describe` and every relation are keyed by it, so renaming a table never moves a cache tag or a policy |
+| `entity(name, { table })` | every statement, index name and foreign key. The entity NAME stays the framework's key — the registry, the cache tag (`entity:account`), `x entities show` and every relation are keyed by it, so renaming a table never moves a cache tag or a policy |
 | `.column(name)` | the DDL, the binding, the decoder, the predicate, the sort key, the cursor. Name it LAST in a chain — the link returns the general column, and only `uuid()` and `timestamp()` keep their own methods across it |
 | `money({ columns })` | per part, merged over `<name>_minor` / `<name>_currency` / `<name>_scale`, so a table that renamed one does not restate the other two. `scale: null` says the table has no scale column: every amount is then at the currency's own minor unit, which is what an absent scale already means |
 
@@ -813,7 +813,7 @@ page.rows[0].author;        // the member row, or null — always present
 | Unknown name | `X_PRELOAD_UNKNOWN_RELATION` at `preload()` itself, not a page later |
 | Shape | `belongsTo` attaches the row or `null`; `hasMany` an array — always present |
 | Statements | one extra per relation, resolved concurrently; naming one twice is one statement |
-| Ceiling | `preload('<relation>', { max })` — the most related rows one relation may attach to one page. Default `MAX_PRELOADED_ROWS` (10,000, the largest page a read may ask for). Past it the read is **refused** (`X_INVARIANT_VIOLATED`), never truncated, and it reads at most one row past the ceiling to know. Naming a relation twice is still one statement: a later call that states `max` replaces the earlier one, as a second `.limit()` does, and one that states none leaves it. The refusal's cause spells the call to write (`.preload('<relation>', { max: n })`); its fix is `x entities describe <entity> --json` |
+| Ceiling | `preload('<relation>', { max })` — the most related rows one relation may attach to one page. Default `MAX_PRELOADED_ROWS` (10,000, the largest page a read may ask for). Past it the read is **refused** (`X_INVARIANT_VIOLATED`), never truncated, and it reads at most one row past the ceiling to know. Naming a relation twice is still one statement: a later call that states `max` replaces the earlier one, as a second `.limit()` does, and one that states none leaves it. The refusal's cause spells the call to write (`.preload('<relation>', { max: n })`); its fix is `x entities show <entity> --json` |
 | Tenancy | carried onto the related read only when the other entity's tenant column shares the name; otherwise `X_TENANCY_UNSCOPED` refuses the related read rather than guess |
 | Terminals | `page()`, `all()`, `one()` preload; `count()`, `countBy()` and `plan()` don't — none reads a row to attach one to |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "25.2.0",
+  "version": "26.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.2.0",
-    "@ultimat3/db": "25.2.0",
-    "@ultimat3/schema": "25.2.0",
-    "@ultimat3/time": "25.2.0"
+    "@ultimat3/core": "26.0.0",
+    "@ultimat3/db": "26.0.0",
+    "@ultimat3/schema": "26.0.0",
+    "@ultimat3/time": "26.0.0"
   }
 }

package/src/aggregate.ts

@@ -64,7 +64,7 @@ export const notAggregatable = (
       fn === 'avg' && kind === 'money'
         ? `${entityName}.sum('${property}') and ${entityName}.count() — divide at the call site, where the rounding is a decision somebody made`
         : candidates.length === 0
-          ? `x entities describe ${entityName} --json   # this entity declares no column ${fn} can be applied to`
+          ? `x entities show ${entityName} --json   # this entity declares no column ${fn} can be applied to`
           : `${entityName}.${fn}('${candidates[0]}')   # ${fn} takes one of: ${candidates.join(', ')}`,
   });
 

package/src/array-element.ts

@@ -52,7 +52,7 @@ const ARRAY_ELEMENT_FIXES = Object.freeze<Record<RefusedElement, string>>({
  * and only a table could show.
  *
  * Not `reject()`: a declaration is repaired by an EDIT, and `reject`'s
- * `x entities describe column --json` is `X_DECLARATION_UNKNOWN` — no entity is named `column`, and
+ * `x entities show column --json` is `X_DECLARATION_UNKNOWN` — no entity is named `column`, and
  * there is no entity at all yet. So each fix is the edit that holds the list instead.
  */
 export const arrayElementRefused = (kind: RefusedElement): EntityError => {

package/src/count-by.ts

@@ -42,7 +42,7 @@ const groupableColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
  * Not `invariantViolated`: its fix opens `x entity explain`, which describes invariants nobody
  * wrote here. What repairs this is one edit to the call — a different column, named in the message
  * because the entity is the only place the answer lives. Only when this entity offers no such
- * column does the fix become a command, and then it is `x entities describe`, which prints the
+ * column does the fix become a command, and then it is `x entities show`, which prints the
  * kinds: there is no call to suggest, since every column it declares would be refused the same way.
  */
 const notGroupable = <Row>(
@@ -57,7 +57,7 @@ const notGroupable = <Row>(
     cause: `${entity.$name}.${operation}('${property}'): ${reason}`,
     fix:
       first === undefined
-        ? `x entities describe ${entity.$name} --json   # this entity declares no column a count can be keyed by`
+        ? `x entities show ${entity.$name} --json   # this entity declares no column a count can be keyed by`
         : `${entity.$name}.${operation}('${first}')   # group by one of: ${groupableColumns(entity).join(', ')}`,
   });
 };

package/src/entity-error.ts

@@ -124,14 +124,12 @@ export class EntityError extends UltimateError {
  * read is not spliced.
  */
 export const describeCommand = (entityName: string): string =>
-  isFixShellSafe(entityName)
-    ? `x entities describe ${entityName} --json`
-    : 'x entities list --json';
+  isFixShellSafe(entityName) ? `x entities show ${entityName} --json` : 'x entities list --json';
 
 /**
  * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
  * given. A literal is an entity that does not exist, and this fix then hands the reader
- * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
+ * `x entities show column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
  * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
  * edit; `refuse.test.ts` fails on a literal here.
  */
@@ -143,7 +141,7 @@ export const invariantViolated = (
   new EntityError({
     code: 'X_INVARIANT_VIOLATED',
     cause: `${entityName}.${invariantName}: ${message}`,
-    fix: `x entities describe ${entityName} --json   # shows the invariant and its SQL CHECK`,
+    fix: `x entities show ${entityName} --json   # shows the invariant and its SQL CHECK`,
   });
 
 export const entityDuplicate = (name: string, existingTable: string): EntityError =>

package/src/entity.ts

@@ -41,7 +41,7 @@ export interface EntityInit<C extends ColumnMap> {
    * cannot cover: `entity('user', { table: 'users', … })` reads and writes the table that is
    * already there, and every statement, index name and foreign key follows it.
    *
-   * The entity NAME stays the framework's key — the registry, the cache tag, `x entities describe`
+   * The entity NAME stays the framework's key — the registry, the cache tag, `x entities show`
    * and every relation are keyed by it — so renaming a table never moves a cache tag or a policy.
    */
   readonly table?: string;

package/src/record-key.ts

@@ -23,7 +23,7 @@ export const recordKeyMissing = (type: string, column: string, value: unknown):
     // `renderFixShellArg` inside the safe branch is verbatim there; it is the call
     // `bun run fix-shell-arg` recognises as the screen.
     fix: isFixShellSafe(type)
-      ? `x entities describe ${renderFixShellArg(type, 'ENTITY')} --json   # lists the primary key; return the whole row (every primary-key column) from the handler that built this one`
+      ? `x entities show ${renderFixShellArg(type, 'ENTITY')} --json   # lists the primary key; return the whole row (every primary-key column) from the handler that built this one`
       : 'x entities list --json   # find this entity, then return the whole row (every primary-key column) from the handler that built this one',
   });
 

package/src/refuse.ts

@@ -1,7 +1,7 @@
 // The two refusals raised while a SCHEMA is still being written — a column and an invariant — and
 // why neither goes through `invariantViolated`: that builder's fix is
-// `x entities describe <entityName> --json`, which needs an entity that exists. Passing the
-// literal `'column'` emitted `x entities describe column --json`, which answers
+// `x entities show <entityName> --json`, which needs an entity that exists. Passing the
+// literal `'column'` emitted `x entities show column --json`, which answers
 // `X_DECLARATION_UNKNOWN` — a fix line that raises a second, unrelated error (issue #290).
 //
 // So the fix is a parameter: every caller supplies the EDIT that repairs its own refusal, the