@gzl10/nexus-sdk 0.2.0 → 0.3.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,11 @@ import { Logger } from 'pino';
  * que pueden ser escritos a archivos o usados en runtime.
  */
 
+/**
+ * Entidades que persisten en BD local
+ * Excluye: action, external, virtual, computed
+ */
+type PersistentEntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition;
 /**
  * Genera código de migración Knex desde EntityDefinition
  *
@@ -24,7 +29,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 +37,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 +50,7 @@ declare function generateZodSchema(entity: EntityDefinition): string;
  * //   ...
  * // }
  */
-declare function generateModel(entity: EntityDefinition): string;
+declare function generateModel(entity: PersistentEntityDefinition): string;
 /**
  * Estructura de permiso generado para insertar en BD
  */
@@ -64,7 +69,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 +81,7 @@ 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;
 
 /**
  * @gzl10/nexus-sdk
@@ -85,6 +90,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 +342,178 @@ 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 - Solo Update/Read, sin lista (site_config)
  */
-interface ReferenceEntity extends BaseEntity {
-    type: 'reference';
-    listFields: Record<string, string>;
-    formFields?: Record<string, FormField>;
-    labelField: string;
-    editMode?: 'modal' | 'page';
-    listType?: ListType;
+interface SingleEntityDefinition extends BaseEntityDefinition {
+    type: 'single';
+    /** Añadir updated_at */
+    timestamps?: boolean;
+    /** Añadir updated_by */
+    audit?: boolean;
 }
 /**
- * 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 +529,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 +562,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 +633,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 +643,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 +696,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 +723,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 OwnershipCondition, type PaginatedResult, type PaginationParams, 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, generateZodSchema, getEntitySubject };

package/dist/index.js

@@ -1,6 +1,13 @@
 // src/generators.ts
+function isPersistentEntity(entity) {
+  const nonPersistent = ["action", "external", "virtual", "computed"];
+  return !nonPersistent.includes(entity.type ?? "collection");
+}
 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 +243,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 = [
     `/**`,
@@ -365,7 +374,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";

package/package.json

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