@gzl10/nexus-sdk 0.2.0 → 0.4.0

package/README.md

@@ -98,17 +98,131 @@ export const projectPlugin: PluginManifest = {
 }
 ```
 
+## EntityDefinition (v0.2.0+)
+
+Define entities as single source of truth for DB, validation, UI, and CASL:
+
+```typescript
+import type { EntityDefinition } from '@gzl10/nexus-sdk'
+
+export const postEntity: EntityDefinition = {
+  table: 'cms_posts',
+  label: 'Posts',
+  labelField: 'title',
+  timestamps: true,
+  audit: true,
+
+  fields: {
+    id: {
+      name: 'id',
+      label: 'ID',
+      input: 'hidden',
+      db: { type: 'uuid', nullable: false, defaultFn: 'uuid' }
+    },
+    title: {
+      name: 'title',
+      label: 'Title',
+      input: 'text',
+      db: { type: 'string', size: 200, nullable: false },
+      validation: { required: true, min: 3, max: 200 },
+      meta: { searchable: true, sortable: true }
+    },
+    content: {
+      name: 'content',
+      label: 'Content',
+      input: 'markdown',
+      db: { type: 'text', nullable: true }
+    },
+    status: {
+      name: 'status',
+      label: 'Status',
+      input: 'select',
+      db: { type: 'string', nullable: false, default: 'draft' },
+      validation: { enum: ['draft', 'published', 'archived'] },
+      options: {
+        static: [
+          { value: 'draft', label: 'Draft' },
+          { value: 'published', label: 'Published' },
+          { value: 'archived', label: 'Archived' }
+        ]
+      }
+    }
+  },
+
+  casl: {
+    ownership: { field: 'created_by' },
+    permissions: {
+      ADMIN: { actions: ['manage'] },
+      EDITOR: { actions: ['create', 'read', 'update'] },
+      VIEWER: { actions: ['read'] }
+    }
+  }
+}
+```
+
+### Code Generators
+
+Generate migrations, Zod schemas, TypeScript models, and CASL permissions:
+
+```typescript
+import {
+  generateMigration,
+  generateZodSchema,
+  generateModel,
+  generateCaslPermissions
+} from '@gzl10/nexus-sdk'
+
+// Generate Knex migration code
+const migrationCode = generateMigration(postEntity)
+
+// Generate Zod validation schemas
+const zodCode = generateZodSchema(postEntity)
+// Creates: createPostSchema, updatePostSchema, postParamsSchema, postQuerySchema
+
+// Generate TypeScript interface
+const modelCode = generateModel(postEntity)
+// Creates: export interface Post { ... }
+
+// Generate CASL permissions for seeding
+const permissions = generateCaslPermissions(postEntity)
+// Returns: Array<{ role, action, subject, conditions, fields, inverted }>
+```
+
 ## Main Types
 
 ### Manifests & Context
 
 | Type | Description |
 |------|-------------|
-| `ModuleManifest` | Defines a module: routes, migrations, seeds, CRUD entities |
+| `ModuleManifest` | Defines a module: routes, migrations, seeds, entities |
 | `PluginManifest` | Groups modules under a plugin with shared metadata |
 | `ModuleContext` | Context injected by Nexus: `db`, `logger`, `helpers`, `services`, `abilities` |
-| `ModuleEntity` | Declarative entity configuration for CRUD UI |
-| `FormField` | Form field configuration with validation |
+
+### Entity Definition System
+
+| Type | Description |
+|------|-------------|
+| `EntityDefinition` | Complete entity definition (DB, UI, validation, CASL) |
+| `FieldDefinition` | Field configuration with DB, UI, and validation settings |
+| `FieldDbConfig` | Database column configuration |
+| `FieldRelation` | Foreign key configuration |
+| `EntityCaslConfig` | CASL authorization configuration |
+
+### Entity Types (Discriminated Union)
+
+| Type | Description |
+|------|-------------|
+| `CollectionEntity` | Full CRUD (users, posts) |
+| `ReferenceEntity` | Catalogs with admin CRUD (countries) |
+| `SingleEntity` | Singleton, update/read only (site_config) |
+| `ConfigEntity` | Per-module config, singleton |
+| `ExternalEntity` | Read-only from external systems |
+| `VirtualEntity` | Orchestration of multiple sources |
+| `ComputedEntity` | KPIs, calculated stats |
+| `ViewEntity` | Optimized read projections |
+| `EventEntity` | Audit logs, append-only |
+| `TempEntity` | TTL-based (cache, sessions) |
+| `ActionEntity` | Commands without persistence |
 
 ### Request & Auth
 

package/dist/index.d.ts

@@ -11,6 +11,27 @@ import { Logger } from 'pino';
  * que pueden ser escritos a archivos o usados en runtime.
  */
 
+/**
+ * Entidades que persisten en BD local con tabla propia
+ * Excluye: action, external, virtual, computed, single (usa tabla compartida)
+ */
+type PersistentEntityDefinition = CollectionEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition;
+/**
+ * Entidades sin persistencia local (read-only o sin BD)
+ */
+type NonPersistentEntityDefinition = ActionEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition;
+/**
+ * Type guard para verificar si una entidad persiste en BD local con tabla propia
+ */
+declare function isPersistentEntity(entity: EntityDefinition): entity is PersistentEntityDefinition;
+/**
+ * Type guard para verificar si es un singleton (usa tabla compartida sys_settings)
+ */
+declare function isSingletonEntity(entity: EntityDefinition): entity is SingleEntityDefinition;
+/**
+ * Type guard para verificar si una entidad tiene tabla propia (para migraciones)
+ */
+declare function hasTable(entity: EntityDefinition): entity is PersistentEntityDefinition;
 /**
  * Genera código de migración Knex desde EntityDefinition
  *
@@ -24,7 +45,7 @@ import { Logger } from 'pino';
  * //   ...
  * // }
  */
-declare function generateMigration(entity: EntityDefinition): string;
+declare function generateMigration(entity: PersistentEntityDefinition): string;
 /**
  * Genera código de schemas Zod desde EntityDefinition
  *
@@ -32,7 +53,7 @@ declare function generateMigration(entity: EntityDefinition): string;
  * const code = generateZodSchema(postEntity)
  * // Genera createPostSchema, updatePostSchema, postParamsSchema, postQuerySchema
  */
-declare function generateZodSchema(entity: EntityDefinition): string;
+declare function generateZodSchema(entity: PersistentEntityDefinition): string;
 /**
  * Genera interface TypeScript desde EntityDefinition
  *
@@ -45,7 +66,16 @@ declare function generateZodSchema(entity: EntityDefinition): string;
  * //   ...
  * // }
  */
-declare function generateModel(entity: EntityDefinition): string;
+declare function generateModel(entity: PersistentEntityDefinition): string;
+/**
+ * Genera schema Zod para entidades read-only
+ * Solo genera el schema de output, no create/update
+ */
+declare function generateReadOnlySchema(entity: ComputedEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition): string;
+/**
+ * Genera interface TypeScript para entidades read-only
+ */
+declare function generateReadOnlyModel(entity: ComputedEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition): string;
 /**
  * Estructura de permiso generado para insertar en BD
  */
@@ -64,7 +94,7 @@ interface GeneratedPermission {
  * const permissions = generateCaslPermissions(postEntity)
  * // Genera array de permisos para insertar en rol_role_permissions
  */
-declare function generateCaslPermissions(entity: EntityDefinition): GeneratedPermission[];
+declare function generateCaslPermissions(entity: PersistentEntityDefinition): GeneratedPermission[];
 /**
  * Genera código de seed para permisos CASL
  *
@@ -76,7 +106,30 @@ declare function generateCaslSeed(entities: EntityDefinition[]): string;
 /**
  * Obtiene el subject CASL de una entidad
  */
-declare function getEntitySubject(entity: EntityDefinition): string;
+declare function getEntitySubject(entity: PersistentEntityDefinition): string;
+/**
+ * Obtiene el nombre de una entidad en PascalCase singular
+ * 'cms_posts' → 'Post', 'rol_role_permissions' → 'RolePermission'
+ */
+declare function getEntityName(entity: EntityDefinition): string;
+/**
+ * Genera archivo completo de schemas Zod para múltiples entidades
+ * Consolida todas las entidades de un módulo en un solo archivo
+ *
+ * @example
+ * const code = generateSchemasFile([userEntity, roleEntity])
+ * writeFileSync('users.schemas.ts', code)
+ */
+declare function generateSchemasFile(definitions: EntityDefinition[]): string;
+/**
+ * Genera archivo completo de modelos TypeScript para múltiples entidades
+ * Consolida todas las entidades de un módulo en un solo archivo
+ *
+ * @example
+ * const code = generateModelsFile([userEntity, roleEntity])
+ * writeFileSync('users.models.ts', code)
+ */
+declare function generateModelsFile(definitions: EntityDefinition[]): string;
 
 /**
  * @gzl10/nexus-sdk
@@ -85,6 +138,23 @@ declare function getEntitySubject(entity: EntityDefinition): string;
  * Use this package to define plugin/module manifests without
  * depending on the full @gzl10/nexus-backend package.
  */
+/**
+ * Unión discriminada de todos los tipos de entidad
+ *
+ * | Type       | Persistencia | CRUD            | Uso principal                    |
+ * |------------|--------------|-----------------|----------------------------------|
+ * | collection | Sí (BD)      | Completo        | Datos de negocio (users, posts)  |
+ * | single     | Sí (BD)      | Update/Read     | Config global (site_config)      |
+ * | external   | No           | Read            | Datos externos (stripe_customers)|
+ * | virtual    | No           | Read            | Orquestación (unified_customers) |
+ * | computed   | No/opcional  | Read            | KPIs, estadísticas               |
+ * | view       | Sí/virtual   | Read            | Lectura optimizada (projections) |
+ * | reference  | Sí           | Read (admin)    | Catálogos (countries, currencies)|
+ * | config     | Sí           | Update/Read     | Config por módulo                |
+ * | event      | Sí           | Append          | Auditoría (audit_logs)           |
+ * | temp       | No (TTL)     | Read/Write      | Cache, sesiones (otp_codes)      |
+ * | action     | No           | Execute         | Operaciones, workflows           |
+ */
 
 type KnexCreateTableBuilder = Knex.CreateTableBuilder;
 type KnexAlterTableBuilder = Knex.AlterTableBuilder;
@@ -320,134 +390,188 @@ interface EntityCaslConfig {
     sensitiveFields?: string[];
 }
 /**
- * Definición completa de una entidad
- *
- * Contiene toda la información necesaria para:
- * - Generar migraciones Knex
- * - Generar schemas Zod
- * - Generar tipos TypeScript
- * - Configurar UI CRUD
- * - Configurar permisos CASL
+ * Propiedades base compartidas por todas las EntityDefinition
  */
-interface EntityDefinition {
+interface BaseEntityDefinition {
+    /** Nombre de tabla en BD (con prefijo: 'cms_posts') */
     table: string;
+    /** Nombre para mostrar en UI */
     label: string;
-    labelField: string;
+    /** Definición de campos */
     fields: Record<string, FieldDefinition>;
-    timestamps?: boolean;
-    audit?: boolean;
-    indexes?: EntityIndex[];
+    /** Autorización CASL */
     casl?: EntityCaslConfig;
 }
-/**
- * Propiedades base compartidas por todas las entidades
- */
-interface BaseEntity {
-    name: string;
-    label: string;
-}
 /**
  * Entidad de colección - CRUD completo (users, posts, orders)
  * Default cuando no se especifica type
  */
-interface CollectionEntity extends BaseEntity {
+interface CollectionEntityDefinition extends BaseEntityDefinition {
     type?: 'collection';
-    listFields: Record<string, string>;
-    formFields?: Record<string, FormField>;
+    /** Campo para mostrar en selects/referencias */
     labelField: string;
-    editMode?: 'modal' | 'page';
-    listType?: ListType;
+    /** Añadir created_at, updated_at */
+    timestamps?: boolean;
+    /** Añadir created_by, updated_by */
+    audit?: boolean;
+    /** Índices compuestos */
+    indexes?: EntityIndex[];
 }
 /**
- * Entidad de referencia - Catálogos con CRUD admin (countries, currencies)
+ * Entidad singleton - Un solo registro en tabla compartida sys_settings
+ * Usa key-value: key identifica el registro, value es JSON con la estructura de fields
+ *
+ * @example
+ * // site_config singleton
+ * { type: 'single', key: 'site_config', label: 'Site Config', fields: { siteName: {...}, logo: {...} } }
+ * // Se guarda en sys_settings como: { key: 'site_config', value: { siteName: 'Mi App', logo: '...' } }
  */
-interface ReferenceEntity extends BaseEntity {
-    type: 'reference';
-    listFields: Record<string, string>;
-    formFields?: Record<string, FormField>;
-    labelField: string;
-    editMode?: 'modal' | 'page';
-    listType?: ListType;
+interface SingleEntityDefinition {
+    type: 'single';
+    /** Clave única en tabla sys_settings (ej: 'site_config', 'smtp_settings') */
+    key: string;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Definición de campos (estructura del JSON value) */
+    fields: Record<string, FieldDefinition>;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
 /**
- * Entidad temporal - CRUD con TTL (otp_codes, cache)
+ * Entidad de referencia - Catálogos con CRUD admin (countries, currencies)
  */
-interface TempEntity extends BaseEntity {
-    type: 'temp';
-    listFields: Record<string, string>;
-    formFields?: Record<string, FormField>;
+interface ReferenceEntityDefinition extends BaseEntityDefinition {
+    type: 'reference';
+    /** Campo para mostrar en selects/referencias */
     labelField: string;
-    editMode?: 'modal' | 'page';
-    listType?: ListType;
+    /** Añadir created_at, updated_at */
+    timestamps?: boolean;
+    /** Índices compuestos */
+    indexes?: EntityIndex[];
 }
 /**
- * Entidad singleton - Solo Update/Read, sin lista (site_config)
+ * Entidad de eventos - Logs de auditoría, append-only
  */
-interface SingleEntity extends BaseEntity {
-    type: 'single';
-    formFields?: Record<string, FormField>;
+interface EventEntityDefinition extends BaseEntityDefinition {
+    type: 'event';
+    /** Campo para mostrar en listas */
+    labelField: string;
+    /** Siempre true para eventos */
+    timestamps: true;
 }
 /**
- * Entidad de configuración - Config por módulo, singleton
+ * Entidad de acción - Comandos/operaciones sin persistencia
  */
-interface ConfigEntity extends BaseEntity {
-    type: 'config';
-    formFields?: Record<string, FormField>;
+interface ActionEntityDefinition {
+    type: 'action';
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Solo campos de formulario, sin BD */
+    fields: Record<string, FieldDefinition>;
 }
 /**
- * Entidad externa - Read-only desde sistemas externos (stripe_customers)
+ * Entidad externa - Datos de APIs externas (stripe_customers, github_repos)
+ * Read-only, sin persistencia local
  */
-interface ExternalEntity extends BaseEntity {
+interface ExternalEntityDefinition {
     type: 'external';
-    listFields: Record<string, string>;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
     labelField: string;
-    listType?: ListType;
+    /** Definición de campos (estructura esperada del API externo) */
+    fields: Record<string, FieldDefinition>;
+    /** Configuración del origen externo */
+    source: {
+        /** Tipo de origen */
+        provider: string;
+        /** Endpoint o recurso */
+        endpoint?: string;
+    };
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
 /**
  * Entidad virtual - Orquestación de múltiples fuentes (unified_customers)
+ * Read-only, combina datos de varias entidades
  */
-interface VirtualEntity extends BaseEntity {
+interface VirtualEntityDefinition {
     type: 'virtual';
-    listFields: Record<string, string>;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
     labelField: string;
-    listType?: ListType;
+    /** Definición de campos (esquema unificado) */
+    fields: Record<string, FieldDefinition>;
+    /** Fuentes de datos que se combinan */
+    sources: string[];
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
 /**
- * Entidad computada - KPIs, estadísticas calculadas
+ * Entidad computed - KPIs, estadísticas, métricas calculadas
+ * Read-only, puede cachear opcionalmente
  */
-interface ComputedEntity extends BaseEntity {
+interface ComputedEntityDefinition {
     type: 'computed';
-    listFields: Record<string, string>;
-    labelField: string;
-    listType?: ListType;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
+    labelField?: string;
+    /** Definición de campos (estructura del resultado) */
+    fields: Record<string, FieldDefinition>;
+    /** Tiempo de cache en segundos (0 = sin cache) */
+    cacheTtl?: number;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
 /**
- * Entidad vista - Proyección optimizada para lectura
+ * Entidad view - Vista optimizada para lectura (projections, denormalizaciones)
+ * Read-only, puede ser vista de BD o virtual
  */
-interface ViewEntity extends BaseEntity {
+interface ViewEntityDefinition {
     type: 'view';
-    listFields: Record<string, string>;
+    /** Tabla o vista en BD (puede ser VIEW SQL) */
+    table: string;
+    /** Nombre para mostrar en UI */
+    label: string;
+    /** Campo para mostrar en selects/referencias */
     labelField: string;
-    listType?: ListType;
+    /** Definición de campos */
+    fields: Record<string, FieldDefinition>;
+    /** Entidad fuente de la que deriva */
+    sourceEntity?: string;
+    /** Autorización CASL */
+    casl?: EntityCaslConfig;
 }
 /**
- * Entidad de eventos - Logs de auditoría, append-only
+ * Entidad config - Configuración por módulo/tenant
+ * Similar a single pero con scope
  */
-interface EventEntity extends BaseEntity {
-    type: 'event';
-    listFields: Record<string, string>;
-    labelField: string;
-    listType?: ListType;
+interface ConfigEntityDefinition extends BaseEntityDefinition {
+    type: 'config';
+    /** Scope de la configuración */
+    scope?: 'global' | 'module' | 'tenant' | 'user';
+    /** Añadir updated_at */
+    timestamps?: boolean;
+    /** Añadir updated_by */
+    audit?: boolean;
 }
 /**
- * Entidad de acción - Comandos/operaciones sin persistencia
+ * Entidad temporal - Cache, sesiones, OTP codes
+ * Con TTL automático, sin auditoría
  */
-interface ActionEntity extends BaseEntity {
-    type: 'action';
-    formFields?: Record<string, FormField>;
+interface TempEntityDefinition extends BaseEntityDefinition {
+    type: 'temp';
+    /** Tiempo de vida en segundos */
+    ttl: number;
+    /** Campo para mostrar en listas (opcional) */
+    labelField?: string;
+    /** Índices para búsqueda rápida */
+    indexes?: EntityIndex[];
 }
 /**
- * Unión discriminada de todos los tipos de entidad
+ * Union de todas las definiciones de entidad
  *
  * | Type       | Persistencia | CRUD            | Uso principal                    |
  * |------------|--------------|-----------------|----------------------------------|
@@ -463,11 +587,7 @@ interface ActionEntity extends BaseEntity {
  * | temp       | No (TTL)     | Read/Write      | Cache, sesiones (otp_codes)      |
  * | action     | No           | Execute         | Operaciones, workflows           |
  */
-type ModuleEntity = CollectionEntity | ReferenceEntity | TempEntity | SingleEntity | ConfigEntity | ExternalEntity | VirtualEntity | ComputedEntity | ViewEntity | EventEntity | ActionEntity;
-/**
- * Helper type para extraer el tipo de entidad
- */
-type EntityType = ModuleEntity['type'];
+type EntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition | ViewEntityDefinition | ReferenceEntityDefinition | ConfigEntityDefinition | EventEntityDefinition | TempEntityDefinition | ActionEntityDefinition;
 /**
  * Requisitos para activar un módulo
  */
@@ -500,6 +620,10 @@ interface ForbiddenErrorConstructor {
  * Permite usar CASL en plugins sin importar @casl/ability directamente
  */
 interface ModuleAbilities {
+    /** Crea una ability CASL para un usuario (acepta argumentos adicionales como permissions) */
+    defineAbilityFor: (user: any, ...args: any[]) => any;
+    /** Empaqueta reglas CASL para enviar al cliente (recibe ability, retorna reglas) */
+    packRules: (ability: any) => unknown[];
     /** Wrapper para verificar permisos contra instancias */
     subject: (type: string, object: Record<string, any>) => unknown;
     /** Error de CASL para throwUnlessCan */
@@ -567,8 +691,8 @@ interface ModuleContext {
     createRouter: () => Router;
     middleware: ModuleMiddlewares;
     registerMiddleware: (name: string, handler: RequestHandler) => void;
-    /** Configuración resuelta de la aplicación */
-    config: Record<string, unknown>;
+    /** Configuración resuelta de la aplicación (permite propiedades tipadas del backend) */
+    config: any;
     errors: {
         AppError: new (message: string, statusCode?: number) => Error;
         NotFoundError: new (message?: string) => Error;
@@ -577,10 +701,8 @@ interface ModuleContext {
         ConflictError: new (message?: string) => Error;
     };
     abilities: ModuleAbilities;
-    events: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-        on: (event: string, listener: (...args: unknown[]) => void) => unknown;
-    };
+    /** Sistema de eventos (EventEmitter2 compatible, permite implementaciones tipadas) */
+    events: any;
     mail: {
         send: (options: {
             to: string | string[];
@@ -632,11 +754,6 @@ interface ModuleManifest {
      * Sus subjects se registran automáticamente.
      */
     definitions?: EntityDefinition[];
-    /**
-     * @deprecated Usar `definitions` en su lugar.
-     * Entidades/tablas del módulo con config CRUD para UI.
-     */
-    entities?: ModuleEntity[];
 }
 /**
  * Categorías disponibles para plugins
@@ -664,4 +781,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-export { type AbilityLike, type ActionEntity, type AuthRequest, type BaseUser, type CaslAction, type CollectionEntity, type ComputedEntity, type ConfigEntity, type CoreServices, type DbType, type EntityCaslConfig, type EntityDefinition, type EntityIndex, type EntityType, type EventEntity, type ExternalEntity, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldValidation, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type FormField, type FormFieldType, type GeneratedPermission, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type ListType, type MigrationHelpers, type ModuleAbilities, type ModuleContext, type ModuleEntity, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PluginAuthRequest, type PluginCategory, type PluginManifest, type ReferenceEntity, type RolePermission, type SingleEntity, type TempEntity, type UsersResolver, type ValidateSchemas, type ValidationSchema, type ViewEntity, type VirtualEntity, generateCaslPermissions, generateCaslSeed, generateMigration, generateModel, generateZodSchema, getEntitySubject };
+export { type AbilityLike, type ActionEntityDefinition, type AuthRequest, type BaseUser, type CaslAction, type CollectionEntityDefinition, type ComputedEntityDefinition, type ConfigEntityDefinition, type CoreServices, type DbType, type EntityCaslConfig, type EntityDefinition, type EntityIndex, type EventEntityDefinition, type ExternalEntityDefinition, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldValidation, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type FormField, type FormFieldType, type GeneratedPermission, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type ListType, type MigrationHelpers, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginCategory, type PluginManifest, type ReferenceEntityDefinition, type RolePermission, type SingleEntityDefinition, type TempEntityDefinition, type UsersResolver, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type VirtualEntityDefinition, generateCaslPermissions, generateCaslSeed, generateMigration, generateModel, generateModelsFile, generateReadOnlyModel, generateReadOnlySchema, generateSchemasFile, generateZodSchema, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };

package/dist/index.js

@@ -1,6 +1,19 @@
 // src/generators.ts
+function isPersistentEntity(entity) {
+  const withoutOwnTable = ["action", "external", "virtual", "computed", "single"];
+  return !withoutOwnTable.includes(entity.type ?? "collection");
+}
+function isSingletonEntity(entity) {
+  return entity.type === "single";
+}
+function hasTable(entity) {
+  return "table" in entity && typeof entity.table === "string";
+}
 function generateMigration(entity) {
-  const { table, fields, timestamps, audit, indexes } = entity;
+  const { table, fields } = entity;
+  const timestamps = "timestamps" in entity ? entity.timestamps : false;
+  const audit = "audit" in entity ? entity.audit : false;
+  const indexes = "indexes" in entity ? entity.indexes : void 0;
   const lines = [
     `import type { ModuleContext, Knex } from '@gzl10/nexus-sdk'`,
     ``,
@@ -236,7 +249,9 @@ function dbTypeToZodType(dbType) {
   }
 }
 function generateModel(entity) {
-  const { table, fields, timestamps, audit } = entity;
+  const { table, fields } = entity;
+  const timestamps = "timestamps" in entity ? entity.timestamps : false;
+  const audit = "audit" in entity ? entity.audit : false;
   const entityName = tableToEntityName(table);
   const lines = [
     `/**`,
@@ -282,19 +297,81 @@ function dbTypeToTsType(db) {
       return "unknown";
   }
 }
+function toPascalCase(str) {
+  return str.split("_").map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}
+function toSingular(str) {
+  if (str.endsWith("ies")) return str.slice(0, -3) + "y";
+  if (str.endsWith("s")) return str.slice(0, -1);
+  return str;
+}
 function tableToEntityName(table) {
   const withoutPrefix = table.replace(/^[a-z]{2,4}_/, "");
-  const singular = withoutPrefix.endsWith("ies") ? withoutPrefix.slice(0, -3) + "y" : withoutPrefix.endsWith("s") ? withoutPrefix.slice(0, -1) : withoutPrefix;
-  return singular.charAt(0).toUpperCase() + singular.slice(1);
+  return toPascalCase(toSingular(withoutPrefix));
 }
 function tableToSubject(table) {
   const match = table.match(/^([a-z]{2,4})_(.+)$/);
   if (!match) return tableToEntityName(table);
   const [, prefix, rest] = match;
   const prefixPascal = prefix.charAt(0).toUpperCase() + prefix.slice(1);
-  const singular = rest.endsWith("ies") ? rest.slice(0, -3) + "y" : rest.endsWith("s") ? rest.slice(0, -1) : rest;
-  const restPascal = singular.charAt(0).toUpperCase() + singular.slice(1);
-  return prefixPascal + restPascal;
+  return prefixPascal + toPascalCase(toSingular(rest));
+}
+function labelToEntityName(label) {
+  const singular = label.endsWith("ies") ? label.slice(0, -3) + "y" : label.endsWith("s") ? label.slice(0, -1) : label;
+  return singular.charAt(0).toUpperCase() + singular.slice(1).replace(/\s+/g, "");
+}
+function generateReadOnlySchema(entity) {
+  const { label, fields } = entity;
+  const entityName = labelToEntityName(label);
+  const lines = [
+    `import { z } from 'zod'`,
+    ``,
+    `// === OUTPUT SCHEMA ===`,
+    `export const ${entityName.toLowerCase()}Schema = z.object({`
+  ];
+  for (const [name, field] of Object.entries(fields)) {
+    const zodType = dbTypeToZodType(field.db.type);
+    const nullable = field.db.nullable ? `.nullable()` : "";
+    lines.push(`  ${name}: ${zodType}${nullable},`);
+  }
+  lines.push(`})`);
+  lines.push(``);
+  lines.push(`// === QUERY ===`);
+  lines.push(`export const ${entityName.toLowerCase()}QuerySchema = z.object({`);
+  lines.push(`  page: z.coerce.number().int().min(1).default(1),`);
+  lines.push(`  limit: z.coerce.number().int().min(1).max(100).default(20),`);
+  for (const [name, field] of Object.entries(fields)) {
+    if (field.meta?.searchable) {
+      const zodType = dbTypeToZodType(field.db.type);
+      lines.push(`  ${name}: ${zodType}.optional(),`);
+    }
+  }
+  lines.push(`})`);
+  lines.push(``);
+  lines.push(`// === INFERRED TYPES ===`);
+  lines.push(`export type ${entityName} = z.infer<typeof ${entityName.toLowerCase()}Schema>`);
+  lines.push(`export type ${entityName}Query = z.infer<typeof ${entityName.toLowerCase()}QuerySchema>`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function generateReadOnlyModel(entity) {
+  const { label, fields } = entity;
+  const entityName = labelToEntityName(label);
+  const lines = [
+    `/**`,
+    ` * ${label}`,
+    ` * Generated from EntityDefinition (${entity.type})`,
+    ` */`,
+    `export interface ${entityName} {`
+  ];
+  for (const [name, field] of Object.entries(fields)) {
+    const tsType = dbTypeToTsType(field.db);
+    const optional = field.db.nullable ? "?" : "";
+    lines.push(`  ${name}${optional}: ${tsType}`);
+  }
+  lines.push(`}`);
+  lines.push(``);
+  return lines.join("\n");
 }
 function getFieldsForRole(entity, role, action) {
   const { fields, casl } = entity;
@@ -365,7 +442,9 @@ function generateCaslPermissions(entity) {
 function generateCaslSeed(entities) {
   const allPermissions = [];
   for (const entity of entities) {
-    allPermissions.push(...generateCaslPermissions(entity));
+    if (isPersistentEntity(entity)) {
+      allPermissions.push(...generateCaslPermissions(entity));
+    }
   }
   if (allPermissions.length === 0) {
     return "// No CASL permissions defined in entities\n";
@@ -430,11 +509,158 @@ function generateCaslSeed(entities) {
 function getEntitySubject(entity) {
   return entity.casl?.subject ?? tableToSubject(entity.table);
 }
+function getEntityName(entity) {
+  if ("table" in entity) {
+    const withoutPrefix = entity.table.replace(/^[a-z]{2,4}_/, "");
+    return toPascalCase(toSingular(withoutPrefix));
+  } else if ("key" in entity) {
+    return toPascalCase(entity.key);
+  } else {
+    return toSingular(entity.label).replace(/\s+/g, "");
+  }
+}
+function dbTypeToZodSimple(type, nullable) {
+  let zod = "";
+  switch (type) {
+    case "string":
+    case "text":
+    case "uuid":
+      zod = "z.string()";
+      break;
+    case "integer":
+      zod = "z.number().int()";
+      break;
+    case "decimal":
+      zod = "z.number()";
+      break;
+    case "boolean":
+      zod = "z.boolean()";
+      break;
+    case "date":
+    case "datetime":
+      zod = "z.string().datetime()";
+      break;
+    case "json":
+      zod = "z.record(z.unknown())";
+      break;
+    default:
+      zod = "z.unknown()";
+  }
+  return nullable ? `${zod}.nullable()` : zod;
+}
+function dbTypeToTsSimple(type) {
+  switch (type) {
+    case "string":
+    case "text":
+    case "uuid":
+      return "string";
+    case "integer":
+    case "decimal":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "date":
+    case "datetime":
+      return "Date";
+    case "json":
+      return "Record<string, unknown>";
+    default:
+      return "unknown";
+  }
+}
+function generateSchemasFile(definitions) {
+  const lines = [
+    "/**",
+    " * AUTO-GENERATED - Do not edit manually",
+    " * Generated from EntityDefinition via @gzl10/nexus-sdk generators",
+    " */",
+    "",
+    "import { z } from 'zod'",
+    ""
+  ];
+  for (const entity of definitions) {
+    const name = getEntityName(entity);
+    lines.push(`// ============================================================================`);
+    lines.push(`// ${name.toUpperCase()} (${entity.type ?? "collection"})`);
+    lines.push(`// ============================================================================`);
+    lines.push("");
+    if (isPersistentEntity(entity)) {
+      const schema = generateZodSchema(entity);
+      const schemaLines = schema.split("\n").filter(
+        (l) => !l.startsWith("import") && l.trim() !== ""
+      );
+      lines.push(...schemaLines);
+    } else if (entity.type === "single") {
+      lines.push(`export const ${name.toLowerCase()}Schema = z.object({`);
+      for (const [fieldName, field] of Object.entries(entity.fields)) {
+        const zodType = dbTypeToZodSimple(field.db.type, field.db.nullable);
+        lines.push(`  ${fieldName}: ${zodType},`);
+      }
+      lines.push("})");
+      lines.push("");
+      lines.push(`export type ${name} = z.infer<typeof ${name.toLowerCase()}Schema>`);
+    } else {
+      const schema = generateReadOnlySchema(entity);
+      const schemaLines = schema.split("\n").filter(
+        (l) => !l.startsWith("import") && l.trim() !== ""
+      );
+      lines.push(...schemaLines);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function generateModelsFile(definitions) {
+  const lines = [
+    "/**",
+    " * AUTO-GENERATED - Do not edit manually",
+    " * Generated from EntityDefinition via @gzl10/nexus-sdk generators",
+    " */",
+    ""
+  ];
+  for (const entity of definitions) {
+    const name = getEntityName(entity);
+    lines.push(`// ============================================================================`);
+    lines.push(`// ${name.toUpperCase()} (${entity.type ?? "collection"})`);
+    lines.push(`// ============================================================================`);
+    lines.push("");
+    if (isPersistentEntity(entity)) {
+      const model = generateModel(entity);
+      const modelLines = model.split("\n");
+      lines.push(...modelLines);
+    } else if (entity.type === "single") {
+      lines.push(`/**`);
+      lines.push(` * ${entity.label}`);
+      lines.push(` * Generated from EntityDefinition (single)`);
+      lines.push(` */`);
+      lines.push(`export interface ${name} {`);
+      for (const [fieldName, field] of Object.entries(entity.fields)) {
+        const tsType = dbTypeToTsSimple(field.db.type);
+        const optional = field.db.nullable ? "?" : "";
+        lines.push(`  ${fieldName}${optional}: ${tsType}`);
+      }
+      lines.push("}");
+    } else {
+      const model = generateReadOnlyModel(entity);
+      lines.push(model);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 export {
   generateCaslPermissions,
   generateCaslSeed,
   generateMigration,
   generateModel,
+  generateModelsFile,
+  generateReadOnlyModel,
+  generateReadOnlySchema,
+  generateSchemasFile,
   generateZodSchema,
-  getEntitySubject
+  getEntityName,
+  getEntitySubject,
+  hasTable,
+  isPersistentEntity,
+  isSingletonEntity
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gzl10/nexus-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "SDK types for creating Nexus plugins and modules",
   "type": "module",
   "main": "./dist/index.js",