@gzl10/nexus-sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -12,10 +12,26 @@ import { Logger } from 'pino';
  */
 
 /**
- * Entidades que persisten en BD local
- * Excluye: action, external, virtual, computed
+ * Entidades que persisten en BD local con tabla propia
+ * Excluye: action, external, virtual, computed, single (usa tabla compartida)
  */
-type PersistentEntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition;
+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
  *
@@ -51,6 +67,15 @@ declare function generateZodSchema(entity: PersistentEntityDefinition): 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
  */
@@ -82,6 +107,29 @@ declare function generateCaslSeed(entities: EntityDefinition[]): string;
  * Obtiene el subject CASL de una entidad
  */
 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
@@ -370,14 +418,24 @@ interface CollectionEntityDefinition extends BaseEntityDefinition {
     indexes?: EntityIndex[];
 }
 /**
- * Entidad singleton - Solo Update/Read, sin lista (site_config)
+ * 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 SingleEntityDefinition extends BaseEntityDefinition {
+interface SingleEntityDefinition {
     type: 'single';
-    /** Añadir updated_at */
-    timestamps?: boolean;
-    /** Añadir updated_by */
-    audit?: boolean;
+    /** 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 de referencia - Catálogos con CRUD admin (countries, currencies)
@@ -723,4 +781,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-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 };
+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,7 +1,13 @@
 // src/generators.ts
 function isPersistentEntity(entity) {
-  const nonPersistent = ["action", "external", "virtual", "computed"];
-  return !nonPersistent.includes(entity.type ?? "collection");
+  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 } = entity;
@@ -291,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;
@@ -441,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.3.0",
+  "version": "0.4.0",
   "description": "SDK types for creating Nexus plugins and modules",
   "type": "module",
   "main": "./dist/index.js",