synthra 0.1.0

data/lib/synthra/api.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+# =============================================================================
+# Synthra Public API
+# =============================================================================
+#
+# This module contains all public API methods for Synthra.
+# It's mixed into the main Synthra module to provide a clean interface.
+#
+# =============================================================================
+
+module Synthra
+  # Valid generation modes, in dispatch order (see Generator::Modes). Exposed so callers can
+  # discover the accepted `mode:` values instead of guessing.
+  MODES = %i[random edge invalid hostile mixed].freeze
+
+  # Public API methods for Synthra
+  #
+  # This module is extended into Synthra to provide all public methods.
+  # Separating the API from configuration keeps the main module clean.
+  #
+  module API
+    # ========================================================================
+    # Configuration API
+    # ========================================================================
+
+    # Returns the global configuration instance
+    #
+    # @return [Configuration] the global configuration singleton
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure Synthra with a block
+    #
+    # @yield [Configuration] the configuration object to modify
+    # @return [void]
+    #
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to default values
+    #
+    # @return [void]
+    #
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # ========================================================================
+    # Loading & Parsing API
+    # ========================================================================
+
+    # Load and parse a single DSL file
+    #
+    # @param path [String] path to the DSL file
+    # @return [Schema] the parsed schema object
+    # @raise [Errors::ParseError] if the DSL syntax is invalid
+    #
+    def load(path)
+      registry = Registry.new
+      registry.load_file(path)
+      registry.schemas.values.first
+    end
+
+    # Parse a DSL string and return the first schema
+    #
+    # @param source [String] DSL source code
+    # @return [Schema] the parsed schema object
+    #
+    def parse(source)
+      registry = Registry.new
+      registry.load_string(source)
+      registry.schemas.values.first
+    end
+
+    # Parse a DSL string and return ALL schemas it defines (not just the first).
+    #
+    # `parse`/`load` return a single schema for convenience, which silently drops the rest of a
+    # multi-schema file. Use these when a source may define more than one schema.
+    #
+    # @param source [String] DSL source code
+    # @return [Array<Schema>] every schema defined in the source
+    def parse_all(source)
+      registry = Registry.new
+      registry.load_string(source)
+      registry.schemas.values
+    end
+
+    # Load a DSL file and return ALL schemas it defines (not just the first).
+    #
+    # @param path [String] path to the DSL file
+    # @return [Array<Schema>] every schema defined in the file
+    def load_all(path)
+      registry = Registry.new
+      registry.load_file(path)
+      registry.schemas.values
+    end
+
+    # ========================================================================
+    # Native Engine API
+    # ========================================================================
+
+    # Check if native Rust engine is available
+    #
+    # @return [Boolean] true if native extension is available
+    #
+    def native_available?
+      NativeEngine.available?
+    end
+
+    # Create a native engine for a schema
+    #
+    # @param schema [Schema] the schema to use
+    # @param locale [String] locale for data generation
+    # @return [NativeEngine] configured native engine
+    #
+    def native_engine(schema, locale: "en")
+      NativeEngine.new(schema, locale: locale)
+    end
+
+    # Generate records using native engine
+    #
+    # @param schema_or_dsl [Schema, String] schema instance or DSL string
+    # @param count [Integer] number of records to generate
+    # @param seed [Integer, nil] random seed for reproducibility
+    # @param locale [String] locale for data generation
+    # @param threads [Integer, nil] number of threads
+    # @return [Array<Hash>] generated records
+    #
+    def generate_native(schema_or_dsl, count, seed: nil, locale: "en", threads: nil)
+      schema = schema_or_dsl.is_a?(String) ? parse(schema_or_dsl) : schema_or_dsl
+      engine = NativeEngine.new(schema, locale: locale, threads: threads)
+      engine.generate_many(count, seed: seed)
+    end
+
+    # Generate records to file using native engine
+    #
+    # @param schema_or_dsl [Schema, String] schema instance or DSL string
+    # @param count [Integer] number of records to generate
+    # @param path [String] output file path
+    # @param seed [Integer, nil] random seed
+    # @param locale [String] locale for data generation
+    # @param format [String] output format: "jsonl", "json", "csv"
+    # @param threads [Integer, nil] number of threads
+    # @return [Integer] number of records written
+    #
+    def generate_native_to_file(schema_or_dsl, count, path, seed: nil, locale: "en", format: "jsonl", threads: nil)
+      schema = schema_or_dsl.is_a?(String) ? parse(schema_or_dsl) : schema_or_dsl
+      engine = NativeEngine.new(schema, locale: locale, threads: threads)
+      engine.generate_to_file(count, path, seed: seed, format: format)
+    end
+
+    # ========================================================================
+    # Registration API
+    # ========================================================================
+
+    # Register a custom type generator
+    #
+    # @param name [String, Symbol] the type name to use in DSL files
+    # @param klass [Class, nil] optional class inheriting from Types::Base
+    # @yield [rng, context, args, mode] block for generating values
+    # @return [void]
+    #
+    def register_type(name, klass = nil, &block)
+      Types::Registry.register(name.to_s, klass, &block)
+    end
+
+    # Register a custom function for computed fields
+    #
+    # @param name [Symbol] the function name
+    # @param force [Boolean] if true, overwrites existing function
+    # @yield [context] block that computes the value
+    # @return [void]
+    #
+    def register_function(name, force: false, &block)
+      Functions::Registry.register(name, force: force, &block)
+    end
+
+    # Register a custom behavior
+    #
+    # @param name [Symbol] the behavior name
+    # @param klass [Class, nil] optional class inheriting from Behaviors::Base
+    # @yield [result, context, value] block for applying behavior
+    # @return [void]
+    #
+    def register_behavior(name, klass = nil, &block)
+      Behaviors::Registry.register(name, klass, &block)
+    end
+
+    # ========================================================================
+    # Export API - Schema Exports
+    # ========================================================================
+
+    # Export schema to JSON Schema format
+    def to_json_schema(schema, registry: nil)
+      Export::JsonSchema.new(schema, registry: registry).export
+    end
+
+    # Export schema to TypeScript interface
+    def to_typescript(schema, registry: nil, comments: false)
+      Export::Typescript.new(schema, registry: registry, comments: comments).export
+    end
+
+    # Export all schemas to TypeScript
+    def to_typescript_all(registry)
+      Export::Typescript.export_all(registry)
+    end
+
+    # Export schema to SQL CREATE TABLE
+    def to_sql(schema, registry: nil, dialect: :postgresql)
+      Export::Sql.new(schema, registry: registry, dialect: dialect).export
+    end
+
+    # Export all schemas to SQL
+    def to_sql_all(registry, dialect: :postgresql)
+      Export::Sql.export_all(registry, dialect: dialect)
+    end
+
+    # Export schema to GraphViz DOT format
+    def to_graphviz(schema = nil, registry: nil, direction: "LR", group: false)
+      Export::Graphviz.new(schema, registry: registry, direction: direction, group: group).export
+    end
+
+    # Export schema to JavaScript with JSDoc
+    def to_javascript(schema, registry: nil)
+      Export::Javascript.new(schema, registry: registry).export
+    end
+
+    # Export all schemas to JavaScript
+    def to_javascript_all(registry)
+      Export::Javascript.export_all(registry)
+    end
+
+    # Export schema to Python
+    def to_python(schema, registry: nil, style: :pydantic)
+      Export::Python.new(schema, registry: registry, style: style).export
+    end
+
+    # Export all schemas to Python
+    def to_python_all(registry, style: :pydantic)
+      Export::Python.export_all(registry, style: style)
+    end
+
+    # Export schema to GraphQL
+    def to_graphql(schema, registry: nil)
+      Export::Graphql.new(schema, registry: registry).export
+    end
+
+    # Export all schemas to GraphQL
+    def to_graphql_all(registry)
+      Export::Graphql.export_all(registry)
+    end
+
+    # ========================================================================
+    # Export API - Data Exports
+    # ========================================================================
+
+    # Export generated data as CSV
+    def to_csv(schema, registry: nil, count: 10, seed: nil, mode: :random)
+      Export::Csv.new(schema, registry: registry, count: count, seed: seed, mode: mode).export
+    end
+
+    # Export generated data as JSON
+    def to_json(schema, registry: nil, count: 10, seed: nil, mode: :random, pretty: true, envelope: nil)
+      Export::JsonData.new(schema, registry: registry, count: count, seed: seed, mode: mode, pretty: pretty, envelope: envelope).export
+    end
+
+    # Export generated data as SQL INSERT statements
+    def to_sql_insert(schema, registry: nil, count: 10, seed: nil, dialect: :postgresql, batch_insert: false)
+      Export::SqlInsert.new(schema, registry: registry, count: count, seed: seed, dialect: dialect, batch_insert: batch_insert).export
+    end
+
+    # Export generated data as YAML
+    def to_yaml(schema, registry: nil, count: 10, seed: nil, root_key: nil)
+      Export::YamlData.new(schema, registry: registry, count: count, seed: seed, root_key: root_key).export
+    end
+
+    # Export generated data as XML
+    def to_xml(schema, registry: nil, count: 10, seed: nil, root: nil, item: nil)
+      Export::XmlData.new(schema, registry: registry, count: count, seed: seed, root: root, item: item).export
+    end
+
+    # ========================================================================
+    # Export Utilities
+    # ========================================================================
+
+    # Export to file with auto-generated filename
+    def export_to_file(format, schema, output_dir: ".", **options)
+      Export.export_to_file(format, schema, output_dir: output_dir, **options)
+    end
+
+    # Get file extension for export format
+    def export_extension(format)
+      Export.file_extension(format)
+    end
+
+    # Generate auto filename for export
+    def export_filename(schema_name, format)
+      Export.auto_filename(schema_name, format)
+    end
+
+    # Export to any supported format
+    def export(format, schema, **options)
+      Export.export(format, schema, **options)
+    end
+
+    # List available export formats
+    def export_formats
+      Export.available_formats
+    end
+
+    # List schema export formats
+    def schema_export_formats
+      Export.schema_formats
+    end
+
+    # List data export formats
+    def data_export_formats
+      Export.data_formats
+    end
+
+    # ========================================================================
+    # Factory Bot Integration
+    # ========================================================================
+
+    # Define a factory using a Synthra schema
+    #
+    # @param factory_name [Symbol] the factory name
+    # @param schema [String] schema name
+    # @yield block for defining traits and overrides
+    # @return [void]
+    #
+    # @example
+    #   Synthra.define_factory(:user, schema: "User") do
+    #     trait(:admin) { role { "admin" } }
+    #   end
+    #
+    def define_factory(factory_name, schema:, &block)
+      FactoryBotIntegration.define_factory(factory_name, schema: schema, &block)
+    end
+
+    # ========================================================================
+    # Snapshot Testing
+    # ========================================================================
+
+    # Iterate over all loaded schemas
+    #
+    # @yield [schema] block to execute for each schema
+    #
+    def each_schema(&block)
+      return enum_for(:each_schema) unless block_given?
+      
+      @default_registry ||= Registry.new
+      @default_registry.schemas.each_value(&block)
+    end
+
+    # Load schemas into default registry for iteration
+    #
+    # @param path [String] path to schema file or directory
+    #
+    def load_schemas(path)
+      @default_registry ||= Registry.new
+      if File.directory?(path)
+        @default_registry.load_dir(path)
+      else
+        @default_registry.load_file(path)
+      end
+    end
+
+    # Access the default registry
+    #
+    # @return [Registry] the default schema registry
+    #
+    def registry
+      @default_registry ||= Registry.new
+    end
+  end
+end