Core API - moxaj/mikron GitHub Wiki

Most public functions reside in the mikron.runtime.core namespace. In the scope of this document, consider this namespace implicitly loaded and aliased to mikron.

Reifies a schema definition.

(mikron/schema schema-name schema-def & args)

• schema-name:
  • syntax: an optional qualified keyword
  • semantics: the name of the schema, allows self-reference
• schema-def: a schema definition, see Schema DSL
• & args: a key-value sequence, see Schema options
• return value:
  • syntax: an instance of mikron/Schema
  • semantics: a reified schema compiled from the schema definition

;; Inline schema
(mikron/schema :int)
;; => <reified schema instance>

;; Inline schema with self-reference
(mikron/schema ::x [:tuple [:int [:optional ::x]]])
;; => <reified schema instance>

Reifies a schema definition and registers it globally with the given name.

(mikron/defschema schema-name schema-def & args)

• schema-name:
  • syntax: a qualified keyword
  • semantics: the name of the schema
• schema-def: a schema definition, see Schema DSL
• & args: a key-value sequence, see Schema options
• return value: schema-name

;; Simple reference
(mikron/defschema ::x :int)
;; => :user/x

(mikron/defschema ::y [:vector ::x])
;; => :user/y

;; Circular reference (referenced schemas are resolved at runtime)
(mikron/defschema ::u [:tuple [:int [:optional ::v]]])
;; => :user/u

(mikron/defschema ::v [:tuple [:int [:optional ::u]]])
;; => :user/v

Both mikron/schema and mikron/defschema are macros, therefore receive their arguments unevaluated, thus the following example will throw:

(mikron/schema [:tuple (vec (repeat 16 :byte))])
;; => <exception>

To work around this, you can either define and invoke your own macro:

(defmacro foo []
  `(mikron/schema [:tuple [~@(repeat 16 :byte)]]))

(foo)
;; => <reified schema instance>

... or make use of an e̸xp͏͏̀e͟r͜͝҉i̛͟m͏̕͟e̶nta̧l feature which allows you to evaluate parts of the macro input by marking them with an ^eval tag:

(mikron/schema [:tuple ^eval (vec (repeat 16 :byte))])
;; => <reified schema instance>

Note however that in self-hosted ClojureScript, vars referenced in the marked expressions must be defined in seperate compilation stages (ie. namespaces).

Serializes a value.

(mikron/pack schema value)

• schema: either
  • a reified schema (see Case A and Case B)
  • a qualified keyword to which a schema was registered via mikron/defschema (see Case C)
• value: a value to serialize, must conform to schema, may be wrapped in mikron/DiffedValue (see Diffing and undiffing)
• return value:
  • syntax: an instance of byte[] (Clojure) or ArrayBuffer (ClojureScript)
  • semantics: value serialized to a binary value

;; Case A (not preferred: other schemas cannot reference it)
(def x (mikron/schema :int))
;; => #'user.x

(mikron/pack x 10)
;; => <binary value>

;; Case B (not preferred: inlined)
(mikron/pack (mikron/schema :int) 10)
;; => <binary value>

;; Case C (preferred)
(mikron/defschema ::x :int)
;; => :user/x

(mikron/pack ::x 10)
;; => <binary value>

;; Invalid value
(mikron/pack ::x "10")
;; => <exception>

Not thread safe. If you wish to run multiple packs in parallel, use mikron/allocate-buffer and mikron/with-buffer.

Deserializes a serialized value.

(mikron/unpack schema binary)

• schema: same as in mikron/pack
• binary:
  • syntax: a binary value (an instance of byte[] (Clojure) or ArrayBuffer (ClojureScript))
  • semantics: the value from which to reconstruct a value conforming to schema
• return value:
  • syntax: a value which conforms to schema or :mikron/invalid
  • semantics: the value deserialized from binary (potentionally wrapped in DiffedValue, see Packing and unpacking), or :mikron/invalid if any exception was thrown while deserializing

(mikron/defschema ::x :int)
;; => :user/x

(->> 10
     (mikron/pack ::x)
     (mikron/unpack ::x))
;; => 10

(->> true
     (mikron/pack (schema :boolean))
     (mikron/unpack ::x))
;; => :mikron/invalid

Allocates a new buffer.

(mikron/allocate-buffer size)

• size:
  • syntax: a non-negative integer
  • semantics: the size of the buffer in bytes
• return value:
  • syntax: an instance of mikron.buffer/MikronBuffer
  • semantics: the allocated buffer

(mikron/allocate-buffer 10000)
;; => <buffer instance>

Sets the buffer instance used by mikron/pack and evaluates each instruction in its dynamic scope.

(mikron/with-buffer buffer & body)

• buffer:
  • syntax: an instance of mikron.buffer/MikronBuffer
  • semantics: the buffer to use in subsequent mikron/pack calls
• & body: a sequence expressions
• return value: the value of the last expression in & body

(def buffer (mikron/allocate-buffer 10000))
;; => #'user/buffer

(mikron/with-buffer buffer
  (mikron/pack (mikron/schema :int) 10))
;; => <binary>

Sets the byte buffer factory globally (for all threads). If, for whatever reason, you'd like to use your own mikron.buffer/IMikronByteBuffer implementation, call this once your application loads. All subsequent buffer allocations (via mikron/allocate-buffer) or wraps (via mikron/unpack) will use the current byte buffer factory.

(mikron/set-byte-buffer-factory! byte-buffer-factory)

• byte-buffer-factory:
  • syntax: an instance of mikron.buffer/MikronByteBufferFactory
  • semantics: the byte buffer factory to use
• return value: undefined

;; Define our custom byte buffer implementation
(deftype CustomByteBuffer [...]
  mikron.buffer/IMikronByteBuffer
  ...)
;; => <CustomByteBuffer type>

;; Define a factory implementation which can instantiate our byte buffer implementation
(deftype CustomByteBufferFactory [...]
  mikron.buffer/IMikronByteBufferFactory
  (-allocate ...)
  (-wrap ...))
;; => <CustomByteBufferFactory type>

;; Set the byte buffer factory globally
(mikron/set-byte-buffer-factory! (->CustomByteBufferFactory ...))
;; => nil

;; Constructs a CustomByteBuffer instance via the `-allocate` method of the factory
(def buffer (mikron/allocate-buffer 10000))
;; => #'user/buffer

(def packed-value
  (mikron/with-buffer buffer
    (mikron/pack (schema :int) 10)))
;; => #'user/packed-value

;; Constructs a CustomByteBuffer instance via the `-wrap` method of the factory
(mikron/unpack (schema :int) packed-value)
;; => 10

Checks whether the given value conforms to the schema or not.

(mikron/valid? schema value)

• schema: same as in mikron/pack
• value:
  • syntax: anything
  • semantics: the value whose conformance to check
• return value:
  • syntax: a boolean
  • true if value conforms to schema, false otherwise

(mikron/valid? (mikron/schema :int) 10)
;; => true

(mikron/valid? (mikron/schema :int) "cake")
;; => false

(mikron/gen schema)

• schema: same as in mikron/pack
• return value:
  • syntax: a value which conforms to schema
  • semantics: the freshly generated value

(mikron/gen (mikron/schema :int))
;; => 10

All functions in this section depend on the :diff-paths options provided at the schema definition (see Schema options).

Calculates the difference (in some sense) between two values.

(mikron/diff* schema value-1 value-2)

• schema: same as in mikron/pack
• value-1:
  • syntax: a value which conforms to schema
  • semantics: the old value
• value-2:
  • syntax: a value which conforms to schema
  • semantics: the new value
• return value:
  • syntax: a value whose parts are either equal to :mikron/nil or conform to the appropriate subschema
  • semantics: the value which represents the difference between value-1 and value-2

(mikron/defschema ::x :int :diff-paths true)

(mikron/diff* ::x 10 20)
;; => 20

(mikron/diff* ::x 10 10)
;; => :mikron/nil

Restores a value from an original value and a calculated difference.

(mikron/undiff* schema value-1 value-2)

• schema: same as in mikron/pack
• value-1:
  • syntax: a value which conforms to schema
  • semantics: the old value
• value-2:
  • syntax: a value whose parts are either :mikron/nil or conform to the appropriate subschema
  • semantics: the value which represents the difference between two values conforming to schema
• return value:
  • syntax: a value which conforms to schema
  • semantics: the value reconstructed from value-1 and value-2

(mikron/defschema ::x :int :diff-paths true)

(->> 20
     (mikron/diff* ::x 10)
     (mikron/undiff* ::x 10))
;; => 20

(->> 10
     (mikron/diff* ::x 10)
     (mikron/undiff* ::x 10))
;; => 10

Same as mikron/diff*, but also wraps the returned value in mikron/DiffedValue (which is an opaque container type to ease the consumption by mikron/pack).

(mikron/diff schema value-1 value-2)

• schema: same as in mikron/pack
• value-1:
  • syntax: a value which conforms to schema
  • semantics: the old value
• value-2:
  • syntax: a value which conforms to schema
  • semantics: the new value
• return value:
  • syntax: an instance of mikron/DiffedValue
  • semantics: the value which represents the difference between value-1 and value-2

(mikron/defschema ::x :int :diff-paths true)

(->> 20
     (mikron/diff ::x 10)
     (mikron/pack ::x))
;; => <binary value>

Same as mikron/undiff*, but expects the diffed value to be an instance of mikron/DiffedValue.

(mikron/undiff schema value-1 value-2)

• schema: same as in mikron/pack
• value-1:
  • syntax: a value which conforms to schema
  • semantics: the old value
• value-2:
  • syntax: an instance of mikron/DiffedValue
  • semantics: the value which represents the difference between two values conforming to schema
• return value:
  • syntax: a value which conforms to schema
  • semantics: the value reconstructed from value-1 and value-2

(mikron/defschema ::x :int :diff-paths true)

(->> 20
     (mikron/diff ::x 10)
     (mikron/pack ::x)
     (mikron/unpack ::x)
     (mikron/undiff ::x))
;; => 20