@stacksjs/database 0.74.37 → 0.74.38

package/dist/erd.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The column type a validation rule implies.
+ *
+ * The first rule names the base type - `schema.string().max(100)` is
+ * `[{ name: 'string' }, { name: 'max' }]` - so the head of the list is the
+ * answer and the rest are constraints a diagram does not show.
+ */
+export declare function columnType(attribute: unknown): string;
+/** Every model name a `belongsTo` / `hasMany` / `hasOne` declaration names. */
+export declare function relatedModelNames(raw: unknown): string[];
+/**
+ * Reduce a model definition to the diagram's view of it.
+ *
+ * Trait columns are included because they are real columns: a diagram that
+ * omits `created_at` describes a table that does not exist. `belongsTo`
+ * foreign keys are added for the same reason - they are the columns the
+ * relationships are actually made of, and an ERD without them is a picture of
+ * arrows with nothing underneath.
+ */
+export declare function toDiagrammableModel(definition: {
+    name?: string
+    table?: string
+    primaryKey?: string
+    attributes?: Record<string, unknown>
+    belongsTo?: unknown
+    hasOne?: unknown
+    hasMany?: unknown
+    traits?: Record<string, unknown>
+  } | null | undefined, table: string): DiagrammableModel;
+/**
+ * The relationship lines, deduplicated and ordered.
+ *
+ * One relationship is usually declared twice - `User hasMany Post` and
+ * `Post belongsTo User` are the same edge - and drawing both puts two arrows
+ * between the same pair of boxes. The parent-to-child direction wins, since
+ * that is how an ERD is read.
+ *
+ * A relation naming a model that is not in the set is dropped rather than
+ * drawn: an edge to a table that does not exist is worse than a missing edge,
+ * because it reads as schema rather than as a typo.
+ */
+export declare function relationEdges(models: DiagrammableModel[]): DiagramEdge[];
+/**
+ * A Mermaid `erDiagram` for these models.
+ *
+ * Relationships first, then entities, which is the order Mermaid's own
+ * examples use and the order that reads well: the shape of the schema before
+ * the detail of each table.
+ */
+export declare function renderErd(models: DiagrammableModel[], options?: RenderErdOptions): string;
+/** One model, reduced to what a diagram needs. */
+export declare interface DiagrammableModel {
+  name: string
+  table: string
+  primaryKey: string
+  columns: DiagramColumn[]
+  belongsTo: string[]
+  hasOne: string[]
+  hasMany: string[]
+}
+export declare interface DiagramColumn {
+  name: string
+  type: string
+  key?: 'PK' | 'FK' | 'UK'
+}
+/** One line of the relationship section. */
+export declare interface DiagramEdge {
+  from: string
+  to: string
+  cardinality: string
+  label: string
+}
+export declare interface RenderErdOptions {
+  columns?: boolean
+  only?: string[]
+}

package/dist/erd.js

@@ -0,0 +1,3 @@
+import{foreignKeyForModel}from"./vschema";const SAFE_TYPE=/^[a-z][a-z0-9_]*$/;export function columnType(attribute){const rules=attribute?.validation?.rule?.rules,head=Array.isArray(rules)?rules[0]?.name:void 0;if(typeof head==="string"&&SAFE_TYPE.test(head))return head;const fallback=attribute?.default;if(typeof fallback==="boolean")return"boolean";if(typeof fallback==="number")return"number";if(typeof fallback==="string")return"string";return"unknown"}export function relatedModelNames(raw){if(typeof raw==="string")return[raw];if(Array.isArray(raw))return raw.map((entry)=>typeof entry==="string"?entry:entry?.model).filter((entry)=>Boolean(entry));if(raw&&typeof raw==="object")return Object.keys(raw);return[]}export function toDiagrammableModel(definition,table){const primaryKey=definition?.primaryKey||"id",traits=definition?.traits??{},columns=[{name:primaryKey,type:"number",key:"PK"}];if(traits.useUuid)columns.push({name:"uuid",type:"string",key:"UK"});for(const[name,attribute]of Object.entries(definition?.attributes??{})){const unique=Boolean(attribute?.unique);columns.push({name,type:columnType(attribute),...unique?{key:"UK"}:{}})}const belongsTo=relatedModelNames(definition?.belongsTo);for(const parent of belongsTo){const column=foreignKeyForModel(parent);if(!columns.some((existing)=>existing.name===column))columns.push({name:column,type:"number",key:"FK"})}if(traits.useTimestamps){columns.push({name:"created_at",type:"datetime"});columns.push({name:"updated_at",type:"datetime"})}if(traits.useSoftDeletes)columns.push({name:"deleted_at",type:"datetime"});return{name:definition?.name??table,table,primaryKey,columns,belongsTo,hasOne:relatedModelNames(definition?.hasOne),hasMany:relatedModelNames(definition?.hasMany)}}export function relationEdges(models){const tableByModel=new Map(models.map((model)=>[model.name,model.table])),seen=new Set,edges=[],add=(from,to,cardinality,label)=>{const key=[from,to].sort().join("\x00");if(seen.has(key))return;seen.add(key);edges.push({from,to,cardinality,label})},sorted=[...models].sort((a,b)=>a.table.localeCompare(b.table));for(const model of sorted){for(const child of[...model.hasMany].sort()){const table=tableByModel.get(child);if(table)add(model.table,table,"||--o{","has many")}for(const child of[...model.hasOne].sort()){const table=tableByModel.get(child);if(table)add(model.table,table,"||--o|","has one")}}for(const model of sorted)for(const parent of[...model.belongsTo].sort()){const table=tableByModel.get(parent);if(table)add(table,model.table,"||--o{","has many")}return edges}export function renderErd(models,options={}){const sorted=[...options.only&&options.only.length>0?models.filter((model)=>options.only.includes(model.table)||options.only.includes(model.name)):models].sort((a,b)=>a.table.localeCompare(b.table)),lines=["erDiagram"];for(const edge of relationEdges(sorted))lines.push(`  ${edge.from} ${edge.cardinality} ${edge.to} : "${edge.label}"`);if(options.columns===!1)return lines.join(`
+`);for(const model of sorted){lines.push(`  ${model.table} {`);for(const column of model.columns)lines.push(`    ${column.type} ${column.name}${column.key?` ${column.key}`:""}`);lines.push("  }")}return lines.join(`
+`)}

package/dist/index.d.ts

@@ -125,6 +125,7 @@ export * from './ddl-constraints';
 // VSchema derivation — turns the model relationship graph into a Vitess
 // keyspace topology, co-locating child tables with their parents so joins
 // between them do not scatter across shards.
+export * from './erd';
 export * from './vschema';
 // SQL dialect helpers & connection defaults
 export * from './sql-helpers';

package/dist/index.js

@@ -1 +1 @@
-export{Database,createDatabase,createMysqlDatabase,createPostgresDatabase,createSqliteDatabase}from"./database";export{detectDriver,driverDefaults,getConfigFromEnv,getConnectionString,mergeWithDefaults,validateDriverConfig}from"./driver-config";export*from"./utils";export*from"./types";export*from"./migrations";export{setQueryTracker,logQuery}from"./query-logger";export{addColumnSafely,backfillInBatches,renameColumnSafely}from"./safe-migrations";export*from"./seeder";export*from"./drivers";export*from"./custom";export*from"./auth-tables";export*from"./utc-defaults";export*from"./uuid-columns";export*from"./managed-columns";export*from"./relation-columns";export{ensureNotificationForeignKeys,migrateNotificationTables}from"./notification-tables";export{migrateRbacTables}from"./rbac-tables";export*from"./trait-tables";export*from"./datetime-columns";export*from"./dialect";export*from"./replicas";export*from"./ddl-constraints";export*from"./vschema";export*from"./sql-helpers";export*from"./defaults";export*from"./migration-dialect";export*from"./migration-path";export*from"./migration-ledger";export*from"./model-sources";export*from"./package-migrations";export*from"./package-models";export*from"./shadowed-models";export*from"./ensure-database";export{auditForeignKeys,classifyDeclaredFKs,findFkOrphans,fkKey,getDeclaredFKs,getLiveFKs,getLiveTables}from"./fk-audit";export{auditSchemaDrift,formatSchemaDrift}from"./schema-drift";export{auditUniqueIndexes,getDeclaredUniques,getLiveUniqueIndexes}from"./unique-audit";export{__flushAfterCommitNow,__pendingAfterCommitCount,enqueueAfterCommit,isInTransaction,runInTransactionScope}from"./transaction-context";export{createQueryBuilder,setConfig}from"@stacksjs/query-builder";export{createDynamo,dynamo,EntityQueryBuilder,generateKeyPattern,parseKeyPattern,buildKey,marshall,unmarshall}from"./drivers/dynamodb";
+export{Database,createDatabase,createMysqlDatabase,createPostgresDatabase,createSqliteDatabase}from"./database";export{detectDriver,driverDefaults,getConfigFromEnv,getConnectionString,mergeWithDefaults,validateDriverConfig}from"./driver-config";export*from"./utils";export*from"./types";export*from"./migrations";export{setQueryTracker,logQuery}from"./query-logger";export{addColumnSafely,backfillInBatches,renameColumnSafely}from"./safe-migrations";export*from"./seeder";export*from"./drivers";export*from"./custom";export*from"./auth-tables";export*from"./utc-defaults";export*from"./uuid-columns";export*from"./managed-columns";export*from"./relation-columns";export{ensureNotificationForeignKeys,migrateNotificationTables}from"./notification-tables";export{migrateRbacTables}from"./rbac-tables";export*from"./trait-tables";export*from"./datetime-columns";export*from"./dialect";export*from"./replicas";export*from"./ddl-constraints";export*from"./erd";export*from"./vschema";export*from"./sql-helpers";export*from"./defaults";export*from"./migration-dialect";export*from"./migration-path";export*from"./migration-ledger";export*from"./model-sources";export*from"./package-migrations";export*from"./package-models";export*from"./shadowed-models";export*from"./ensure-database";export{auditForeignKeys,classifyDeclaredFKs,findFkOrphans,fkKey,getDeclaredFKs,getLiveFKs,getLiveTables}from"./fk-audit";export{auditSchemaDrift,formatSchemaDrift}from"./schema-drift";export{auditUniqueIndexes,getDeclaredUniques,getLiveUniqueIndexes}from"./unique-audit";export{__flushAfterCommitNow,__pendingAfterCommitCount,enqueueAfterCommit,isInTransaction,runInTransactionScope}from"./transaction-context";export{createQueryBuilder,setConfig}from"@stacksjs/query-builder";export{createDynamo,dynamo,EntityQueryBuilder,generateKeyPattern,parseKeyPattern,buildKey,marshall,unmarshall}from"./drivers/dynamodb";

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/database",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.37",
+  "version": "0.74.38",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -60,26 +60,26 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.74.37",
-    "@stacksjs/env": "0.74.37",
-    "@stacksjs/error-handling": "0.74.37",
-    "@stacksjs/faker": "^0.74.37",
-    "@stacksjs/features": "0.74.37",
-    "@stacksjs/logging": "0.74.37",
-    "@stacksjs/model-meta": "0.74.37",
-    "@stacksjs/path": "0.74.37",
-    "@stacksjs/query-builder": "^0.74.37",
-    "@stacksjs/security": "0.74.37",
-    "@stacksjs/storage": "0.74.37",
-    "@stacksjs/strings": "0.74.37",
+    "@stacksjs/config": "0.74.38",
+    "@stacksjs/env": "0.74.38",
+    "@stacksjs/error-handling": "0.74.38",
+    "@stacksjs/faker": "^0.74.38",
+    "@stacksjs/features": "0.74.38",
+    "@stacksjs/logging": "0.74.38",
+    "@stacksjs/model-meta": "0.74.38",
+    "@stacksjs/path": "0.74.38",
+    "@stacksjs/query-builder": "^0.74.38",
+    "@stacksjs/security": "0.74.38",
+    "@stacksjs/storage": "0.74.38",
+    "@stacksjs/strings": "0.74.38",
     "@stacksjs/ts-validation": "^0.5.6",
     "bun-query-builder": "^0.2.69",
     "dynamodb-tooling": "^0.3.2"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.74.37",
-    "@stacksjs/router": "0.74.37",
-    "@stacksjs/utils": "0.74.37",
+    "@stacksjs/cli": "0.74.38",
+    "@stacksjs/router": "0.74.38",
+    "@stacksjs/utils": "0.74.38",
     "better-dx": "^0.2.24"
   }
 }