Module: Synthra::API

Included in:
Synthra
Defined in:
lib/synthra/api.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#configuration ⇒ Configuration

Returns the global configuration instance

Returns:



31
32
33
 
# File 'lib/synthra/api.rb', line 31

def configuration
  @configuration ||= Configuration.new
end

#configure {|Configuration| ... } ⇒ void

This method returns an undefined value.

Configure Synthra with a block

Yields:



40
41
42
 
# File 'lib/synthra/api.rb', line 40

def configure
  yield(configuration)
end

#data_export_formats ⇒ Object

List data export formats



321
322
323
 
# File 'lib/synthra/api.rb', line 321

def data_export_formats
  Export.data_formats
end

#define_factory(factory_name, schema:) { ... } ⇒ void

This method returns an undefined value.

Define a factory using a Synthra schema

Examples:

Synthra.define_factory(:user, schema: "User") do
  trait(:admin) { role { "admin" } }
end

Parameters:

  • factory_name (Symbol) —

    the factory name

  • schema (String) —

    schema name

Yields:

  • block for defining traits and overrides



341
342
343
 
# File 'lib/synthra/api.rb', line 341

def define_factory(factory_name, schema:, &block)
  FactoryBotIntegration.define_factory(factory_name, schema: schema, &block)
end

#each_schema {|schema| ... } ⇒ Object

Iterate over all loaded schemas

Yields:

  • (schema) —

    block to execute for each schema



353
354
355
356
357
358
 
# File 'lib/synthra/api.rb', line 353

def each_schema(&block)
  return enum_for(:each_schema) unless block_given?
  
  @default_registry ||= Registry.new
  @default_registry.schemas.each_value(&block)
end

#export(format, schema, **options) ⇒ Object

Export to any supported format



306
307
308
 
# File 'lib/synthra/api.rb', line 306

def export(format, schema, **options)
  Export.export(format, schema, **options)
end

#export_extension(format) ⇒ Object

Get file extension for export format



296
297
298
 
# File 'lib/synthra/api.rb', line 296

def export_extension(format)
  Export.file_extension(format)
end

#export_filename(schema_name, format) ⇒ Object

Generate auto filename for export



301
302
303
 
# File 'lib/synthra/api.rb', line 301

def export_filename(schema_name, format)
  Export.auto_filename(schema_name, format)
end

#export_formats ⇒ Object

List available export formats



311
312
313
 
# File 'lib/synthra/api.rb', line 311

def export_formats
  Export.available_formats
end

#export_to_file(format, schema, output_dir: ".", **options) ⇒ Object

Export to file with auto-generated filename



291
292
293
 
# File 'lib/synthra/api.rb', line 291

def export_to_file(format, schema, output_dir: ".", **options)
  Export.export_to_file(format, schema, output_dir: output_dir, **options)
end

#generate_native(schema_or_dsl, count, seed: nil, locale: "en", threads: nil) ⇒ Array<Hash>

Generate records using native engine

Parameters:

  • schema_or_dsl (Schema, String) —

    schema instance or DSL string

  • count (Integer) —

    number of records to generate

  • seed (Integer, nil) (defaults to: nil) —

    random seed for reproducibility

  • locale (String) (defaults to: "en") —

    locale for data generation

  • threads (Integer, nil) (defaults to: nil) —

    number of threads

Returns:

  • (Array<Hash>) —

    generated records



133
134
135
136
137
 
# File 'lib/synthra/api.rb', line 133

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_native_to_file(schema_or_dsl, count, path, seed: nil, locale: "en", format: "jsonl", threads: nil) ⇒ Integer

Generate records to file using native engine

Parameters:

  • schema_or_dsl (Schema, String) —

    schema instance or DSL string

  • count (Integer) —

    number of records to generate

  • path (String) —

    output file path

  • seed (Integer, nil) (defaults to: nil) —

    random seed

  • locale (String) (defaults to: "en") —

    locale for data generation

  • format (String) (defaults to: "jsonl") —

    output format: "jsonl", "json", "csv"

  • threads (Integer, nil) (defaults to: nil) —

    number of threads

Returns:

  • (Integer) —

    number of records written



150
151
152
153
154
 
# File 'lib/synthra/api.rb', line 150

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

#load(path) ⇒ Schema

Load and parse a single DSL file

Parameters:

  • path (String) —

    path to the DSL file

Returns:

  • (Schema) —

    the parsed schema object

Raises:



62
63
64
65
66
 
# File 'lib/synthra/api.rb', line 62

def load(path)
  registry = Registry.new
  registry.load_file(path)
  registry.schemas.values.first
end

#load_all(path) ⇒ Array<Schema>

Load a DSL file and return ALL schemas it defines (not just the first).

Parameters:

  • path (String) —

    path to the DSL file

Returns:

  • (Array<Schema>) —

    every schema defined in the file



96
97
98
99
100
 
# File 'lib/synthra/api.rb', line 96

def load_all(path)
  registry = Registry.new
  registry.load_file(path)
  registry.schemas.values
end

#load_schemas(path) ⇒ Object

Load schemas into default registry for iteration

Parameters:

  • path (String) —

    path to schema file or directory



364
365
366
367
368
369
370
371
 
# File 'lib/synthra/api.rb', line 364

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

#native_available? ⇒ Boolean

Check if native Rust engine is available

Returns:

  • (Boolean) —

    true if native extension is available



110
111
112
 
# File 'lib/synthra/api.rb', line 110

def native_available?
  NativeEngine.available?
end

#native_engine(schema, locale: "en") ⇒ NativeEngine

Create a native engine for a schema

Parameters:

  • schema (Schema) —

    the schema to use

  • locale (String) (defaults to: "en") —

    locale for data generation

Returns:



120
121
122
 
# File 'lib/synthra/api.rb', line 120

def native_engine(schema, locale: "en")
  NativeEngine.new(schema, locale: locale)
end

#parse(source) ⇒ Schema

Parse a DSL string and return the first schema

Parameters:

  • source (String) —

    DSL source code

Returns:

  • (Schema) —

    the parsed schema object



73
74
75
76
77
 
# File 'lib/synthra/api.rb', line 73

def parse(source)
  registry = Registry.new
  registry.load_string(source)
  registry.schemas.values.first
end

#parse_all(source) ⇒ Array<Schema>

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.

Parameters:

  • source (String) —

    DSL source code

Returns:

  • (Array<Schema>) —

    every schema defined in the source



86
87
88
89
90
 
# File 'lib/synthra/api.rb', line 86

def parse_all(source)
  registry = Registry.new
  registry.load_string(source)
  registry.schemas.values
end

#register_behavior(name, klass = nil) {|result, context, value| ... } ⇒ void

This method returns an undefined value.

Register a custom behavior

Parameters:

  • name (Symbol) —

    the behavior name

  • klass (Class, nil) (defaults to: nil) —

    optional class inheriting from Behaviors::Base

Yields:

  • (result, context, value) —

    block for applying behavior



189
190
191
 
# File 'lib/synthra/api.rb', line 189

def register_behavior(name, klass = nil, &block)
  Behaviors::Registry.register(name, klass, &block)
end

#register_function(name, force: false) {|context| ... } ⇒ void

This method returns an undefined value.

Register a custom function for computed fields

Parameters:

  • name (Symbol) —

    the function name

  • force (Boolean) (defaults to: false) —

    if true, overwrites existing function

Yields:

  • (context) —

    block that computes the value



178
179
180
 
# File 'lib/synthra/api.rb', line 178

def register_function(name, force: false, &block)
  Functions::Registry.register(name, force: force, &block)
end

#register_type(name, klass = nil) {|rng, context, args, mode| ... } ⇒ void

This method returns an undefined value.

Register a custom type generator

Parameters:

  • name (String, Symbol) —

    the type name to use in DSL files

  • klass (Class, nil) (defaults to: nil) —

    optional class inheriting from Types::Base

Yields:

  • (rng, context, args, mode) —

    block for generating values



167
168
169
 
# File 'lib/synthra/api.rb', line 167

def register_type(name, klass = nil, &block)
  Types::Registry.register(name.to_s, klass, &block)
end

#registry ⇒ Registry

Access the default registry

Returns:

  • (Registry) —

    the default schema registry



377
378
379
 
# File 'lib/synthra/api.rb', line 377

def registry
  @default_registry ||= Registry.new
end

#reset_configuration! ⇒ void

This method returns an undefined value.

Reset configuration to default values



48
49
50
 
# File 'lib/synthra/api.rb', line 48

def reset_configuration!
  @configuration = Configuration.new
end

#schema_export_formats ⇒ Object

List schema export formats



316
317
318
 
# File 'lib/synthra/api.rb', line 316

def schema_export_formats
  Export.schema_formats
end

#to_csv(schema, registry: nil, count: 10, seed: nil, mode: :random) ⇒ Object

Export generated data as CSV



262
263
264
 
# File 'lib/synthra/api.rb', line 262

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

#to_graphql(schema, registry: nil) ⇒ Object

Export schema to GraphQL



248
249
250
 
# File 'lib/synthra/api.rb', line 248

def to_graphql(schema, registry: nil)
  Export::Graphql.new(schema, registry: registry).export
end

#to_graphql_all(registry) ⇒ Object

Export all schemas to GraphQL



253
254
255
 
# File 'lib/synthra/api.rb', line 253

def to_graphql_all(registry)
  Export::Graphql.export_all(registry)
end

#to_graphviz(schema = nil, registry: nil, direction: "LR", group: false) ⇒ Object

Export schema to GraphViz DOT format



223
224
225
 
# File 'lib/synthra/api.rb', line 223

def to_graphviz(schema = nil, registry: nil, direction: "LR", group: false)
  Export::Graphviz.new(schema, registry: registry, direction: direction, group: group).export
end

#to_javascript(schema, registry: nil) ⇒ Object

Export schema to JavaScript with JSDoc



228
229
230
 
# File 'lib/synthra/api.rb', line 228

def to_javascript(schema, registry: nil)
  Export::Javascript.new(schema, registry: registry).export
end

#to_javascript_all(registry) ⇒ Object

Export all schemas to JavaScript



233
234
235
 
# File 'lib/synthra/api.rb', line 233

def to_javascript_all(registry)
  Export::Javascript.export_all(registry)
end

#to_json(schema, registry: nil, count: 10, seed: nil, mode: :random, pretty: true, envelope: nil) ⇒ Object

Export generated data as JSON



267
268
269
 
# File 'lib/synthra/api.rb', line 267

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

#to_json_schema(schema, registry: nil) ⇒ Object

Export schema to JSON Schema format



198
199
200
 
# File 'lib/synthra/api.rb', line 198

def to_json_schema(schema, registry: nil)
  Export::JsonSchema.new(schema, registry: registry).export
end

#to_python(schema, registry: nil, style: :pydantic) ⇒ Object

Export schema to Python



238
239
240
 
# File 'lib/synthra/api.rb', line 238

def to_python(schema, registry: nil, style: :pydantic)
  Export::Python.new(schema, registry: registry, style: style).export
end

#to_python_all(registry, style: :pydantic) ⇒ Object

Export all schemas to Python



243
244
245
 
# File 'lib/synthra/api.rb', line 243

def to_python_all(registry, style: :pydantic)
  Export::Python.export_all(registry, style: style)
end

#to_sql(schema, registry: nil, dialect: :postgresql) ⇒ Object

Export schema to SQL CREATE TABLE



213
214
215
 
# File 'lib/synthra/api.rb', line 213

def to_sql(schema, registry: nil, dialect: :postgresql)
  Export::Sql.new(schema, registry: registry, dialect: dialect).export
end

#to_sql_all(registry, dialect: :postgresql) ⇒ Object

Export all schemas to SQL



218
219
220
 
# File 'lib/synthra/api.rb', line 218

def to_sql_all(registry, dialect: :postgresql)
  Export::Sql.export_all(registry, dialect: dialect)
end

#to_sql_insert(schema, registry: nil, count: 10, seed: nil, dialect: :postgresql, batch_insert: false) ⇒ Object

Export generated data as SQL INSERT statements



272
273
274
 
# File 'lib/synthra/api.rb', line 272

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

#to_typescript(schema, registry: nil, comments: false) ⇒ Object

Export schema to TypeScript interface



203
204
205
 
# File 'lib/synthra/api.rb', line 203

def to_typescript(schema, registry: nil, comments: false)
  Export::Typescript.new(schema, registry: registry, comments: comments).export
end

#to_typescript_all(registry) ⇒ Object

Export all schemas to TypeScript



208
209
210
 
# File 'lib/synthra/api.rb', line 208

def to_typescript_all(registry)
  Export::Typescript.export_all(registry)
end

#to_xml(schema, registry: nil, count: 10, seed: nil, root: nil, item: nil) ⇒ Object

Export generated data as XML



282
283
284
 
# File 'lib/synthra/api.rb', line 282

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

#to_yaml(schema, registry: nil, count: 10, seed: nil, root_key: nil) ⇒ Object

Export generated data as YAML



277
278
279
 
# File 'lib/synthra/api.rb', line 277

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