module Surrealist

Main module that provides the json_schema class method and surrealize instance method.

Constants

DEFAULT_NESTING_LEVEL

Default namespaces nesting level

VERSION

Defines the version of Surrealist

Public Class Methods

build_schema(instance:, **args) click to toggle source

Builds hash from schema provided in the object's class and type-checks the values.

@param [Object] instance of a class that has Surrealist included. @param [Hash] args optional arguments

@return [Hash] a hash corresponding to the schema

provided in the object's class. Values will be taken from the return values
of appropriate methods from the object.

@raise Surrealist::UnknownSchemaError if no schema was provided in the object's class.

@raise Surrealist::InvalidTypeError if type-check failed at some point.

@raise Surrealist::UndefinedMethodError if a key defined in the schema

does not have a corresponding method on the object.

@example Define a schema and surrealize the object

class User
  include Surrealist

  json_schema do
    {
      name: String,
      age: Integer,
    }
  end

  def name
    'Nikita'
  end

  def age
    23
  end
end

User.new.build_schema
# => { name: 'Nikita', age: 23 }
# For more examples see README
# File lib/surrealist.rb, line 127
def build_schema(instance:, **args)
  schema = Surrealist::VarsHelper.find_schema(instance.class)
  Surrealist::ExceptionRaiser.raise_unknown_schema!(instance) if schema.nil?

  parameters = config ? config.merge(args) : args

  # TODO: Refactor (something pipeline-like would do here, perhaps a builder of some sort)
  carrier = Surrealist::Carrier.call(parameters)
  copied_schema = Surrealist::Copier.deep_copy(schema)
  built_schema = Builder.new(carrier, copied_schema, instance).call
  wrapped_schema = Surrealist::Wrapper.wrap(built_schema, carrier, instance.class.name)
  carrier.camelize ? Surrealist::HashUtils.camelize_hash(wrapped_schema) : wrapped_schema
end
config() click to toggle source

Reads current default serialization arguments.

@return [Hash] default arguments (@see Surrealist::Carrier)

# File lib/surrealist.rb, line 145
def config
  @default_args || Surrealist::HashUtils::EMPTY_HASH
end
configure(hash = nil) { |carrier| ... } click to toggle source

Sets default serialization arguments with a block

@param [Hash] hash arguments to be set (@see Surrealist::Carrier) @param [Proc] _block a block which will be yielded to Surrealist::Carrier instance

@example set config

Surrealist.configure do |config|
  config.camelize = true
  config.include_root = true
end
# File lib/surrealist.rb, line 159
def configure(hash = nil, &_block)
  if block_given?
    carrier = Surrealist::Carrier.new
    yield(carrier)
    @default_args = carrier.parameters
  else
    @default_args = hash.nil? ? Surrealist::HashUtils::EMPTY_HASH : hash
  end
end
included(base) click to toggle source

@param [Class] base class to include/extend Surrealist.

# File lib/surrealist.rb, line 30
def included(base)
  base.extend(Surrealist::ClassMethods)
  base.include(Surrealist::InstanceMethods)
end
surrealize(instance:, **args) click to toggle source

Dumps the object's methods corresponding to the schema provided in the object's class and type-checks the values.

@param [Boolean] [optional] camelize optional argument for converting hash to camelBack. @param [Boolean] [optional] include_root optional argument for having the root key of the resulting hash

as instance's class name.

@param [Boolean] [optional] include_namespaces optional argument for having root key as a nested hash of

instance's namespaces. Animal::Cat.new.surrealize -> (animal: { cat: { weight: '3 kilos' } })

@param [String] [optional] root optional argument for using a specified root key for the hash @param [Integer] [optional] namespaces_nesting_level level of namespaces nesting.

@return [String] a json-formatted string corresponding to the schema

provided in the object's class. Values will be taken from the return values
of appropriate methods from the object.
# File lib/surrealist.rb, line 82
def surrealize(instance:, **args)
  Oj.dump(build_schema(instance: instance, **args), mode: :compat)
end
surrealize_collection(collection, **args) click to toggle source

Iterates over a collection of Surrealist Objects and maps surrealize to each object.

@param [Object] collection of instances of a class that has Surrealist included. @param [Boolean] [optional] camelize optional argument for converting hash to camelBack. @param [Boolean] [optional] include_root optional argument for having the root key of the resulting hash

as instance's class name.

@param [Boolean] [optional] include_namespaces optional argument for having root key as a nested hash of

instance's namespaces. Animal::Cat.new.surrealize -> (animal: { cat: { weight: '3 kilos' } })

@param [String] [optional] root optional argument for using a specified root key for the hash. @param [Integer] [optional] namespaces_nesting_level level of namespaces nesting. @param [Boolean] [optional] raw optional argument for specifying the expected output format.

@return [JSON | Hash] the Collection#map with elements being json-formatted string corresponding

to the schema provided in the object's class. Values will be taken from the return values
of appropriate methods from the object.

@raise Surrealist::InvalidCollectionError if invalid collection passed.

@example surrealize a given collection of Surrealist objects

Surrealist.surrealize_collection(User.all)
# => "[{\"name\":\"Nikita\",\"age\":23}, {\"name\":\"Alessandro\",\"age\":24}]"
# For more examples see README
# File lib/surrealist.rb, line 58
def surrealize_collection(collection, **args)
  Surrealist::ExceptionRaiser.raise_invalid_collection! unless Helper.collection?(collection)

  result = collection.map do |object|
    Helper.surrealist?(object.class) ? __build_schema(object, args) : object
  end

  args[:raw] ? result : Oj.dump(result, mode: :compat)
end

Private Class Methods

__build_schema(object, **args) click to toggle source

Checks if there is a serializer (< Surrealist::Serializer) defined for the object and delegates surrealization to it.

@param [Object] object serializable object @param [Hash] args optional arguments passed to surrealize_collection

@return [Hash] a hash corresponding to the schema

provided in the object's class. Values will be taken from the return values
of appropriate methods from the object.
# File lib/surrealist.rb, line 180
def __build_schema(object, **args)
  return args[:serializer].new(object, args[:context].to_h).build_schema(args) if args[:serializer]

  if (serializer = Surrealist::VarsHelper.find_serializer(object.class, tag: args[:for]))
    serializer.new(object, args[:context].to_h).build_schema(args)
  else
    build_schema(instance: object, **args)
  end
end