@famgia/omnify-core

Core engine for the Omnify schema system. Provides schema loading, validation, plugin management, and generator execution.

Installation

npm install @famgia/omnify-core

Usage

Load and Validate Schemas

import { loadSchemas, validateSchemas } from '@famgia/omnify-core';

// Load schemas from directory
const schemas = await loadSchemas('./schemas');

// Validate schemas
const result = validateSchemas(schemas);

if (!result.valid) {
  for (const error of result.errors) {
    console.error(`${error.schemaName}: ${error.message}`);
  }
}

Plugin Manager

import { PluginManager } from '@famgia/omnify-core';
import type { OmnifyPlugin } from '@famgia/omnify-types';

const manager = new PluginManager({
  cwd: process.cwd(),
  verbose: true,
  logger: console,
});

// Register a plugin
await manager.register(myPlugin);

// Get all registered custom types
const customTypes = manager.getCustomTypes();

// Run all generators
const result = await manager.runGenerators(schemas);

if (result.success) {
  for (const output of result.outputs) {
    console.log(`Generated: ${output.path}`);
  }
}

Generator Runner (DAG-based)

import { GeneratorRunner } from '@famgia/omnify-core';

const runner = new GeneratorRunner({
  cwd: process.cwd(),
  verbose: true,
  logger: console,
});

// Register generators (automatically sorts by dependencies)
runner.registerAll([
  {
    definition: schemaGenerator,
    pluginName: 'my-plugin',
    pluginConfig: {},
  },
  {
    definition: migrationGenerator,
    pluginName: 'my-plugin',
    pluginConfig: {},
  },
]);

// Execute in topological order
const result = await runner.runAll(schemas);

Error Handling

import { OmnifyError } from '@famgia/omnify-core';

try {
  await loadSchemas('./invalid-path');
} catch (error) {
  if (error instanceof OmnifyError) {
    console.error(`[${error.code}] ${error.message}`);
    if (error.schemaName) {
      console.error(`  Schema: ${error.schemaName}`);
    }
    if (error.suggestion) {
      console.error(`  Suggestion: ${error.suggestion}`);
    }
  }
}

API Reference

Functions

| Function | Description | |----------|-------------| | loadSchemas(path) | Load all YAML/JSON schema files from directory | | loadSchema(filePath) | Load a single schema file | | validateSchemas(schemas) | Validate schema collection | | validateSchema(schema) | Validate a single schema |

Classes

PluginManager

Manages plugin registration and generator execution.

new PluginManager(options: PluginManagerOptions)

interface PluginManagerOptions {
  cwd: string;
  verbose?: boolean;
  logger?: PluginLogger;
}

Methods:

• register(plugin) - Register a plugin
• getPlugin(name) - Get plugin by name
• getCustomTypes() - Get all custom types
• hasCustomType(name) - Check if custom type exists
• getGenerators() - Get all registered generators
• runGenerators(schemas) - Execute all generators

GeneratorRunner

Executes generators in dependency order using topological sort.

new GeneratorRunner(options: GeneratorRunnerOptions)

Methods:

• register(generator) - Register a single generator
• registerAll(generators) - Register multiple generators
• runAll(schemas) - Execute all generators in order
• getOrder() - Get execution order (for debugging)

OmnifyError

Custom error class with detailed error information.

class OmnifyError extends Error {
  code: string;
  schemaName?: string;
  propertyName?: string;
  filePath?: string;
  suggestion?: string;
}

Plugin System

Creating a Plugin

import type { OmnifyPlugin } from '@famgia/omnify-types';

const myPlugin: OmnifyPlugin = {
  name: 'my-plugin',
  version: '1.0.0',

  // Lifecycle hooks
  setup: async (context) => {
    console.log('Plugin initialized');
  },

  teardown: async () => {
    console.log('Plugin cleanup');
  },

  // Custom types
  types: [
    {
      name: 'Money',
      typescript: 'number',
      laravel: 'decimal',
      laravelParams: [10, 2],
    },
  ],

  // Generators
  generators: [
    {
      name: 'my-generator',
      description: 'Generate custom files',
      dependsOn: ['other-generator'],

      generate: async (ctx) => {
        return [{
          path: 'output/file.ts',
          content: '// Generated',
          type: 'other',
        }];
      },
    },
  ],
};

Generator Dependencies

Generators can specify dependsOn to control execution order:

generators: [
  {
    name: 'schema-generator',
    generate: async (ctx) => { /* ... */ },
  },
  {
    name: 'migration-generator',
    dependsOn: ['schema-generator'], // Runs after schema-generator
    generate: async (ctx) => {
      // Access previous outputs
      const schemaOutputs = ctx.previousOutputs.get('schema-generator');
      // ...
    },
  },
]

The GeneratorRunner uses Kahn's algorithm for topological sorting and detects circular dependencies.

Validation Rules

The validator checks for:

• Valid schema structure (name, kind, properties)
• Valid property types (built-in or custom)
• Valid association types and references
• Unique property names
• Required fields presence
• Circular reference detection

Related Packages

• @famgia/omnify-types - Type definitions
• @famgia/omnify-cli - CLI tool
• @famgia/omnify-laravel - Laravel generator
• @famgia/omnify-atlas - Atlas adapter

License

MIT