strata_document/schema

Portable phantom-typed fields and whole-document record schemas.

A Field(tag, value) can only be used with a Document(tag). Record schemas derive their decoder and per-key writes from the same Prop declarations, preventing the two directions from drifting apart.

Types

Field

A typed key with its JSON encoder and decoder.

pub type Field(a, b)

FieldError

The reason a typed field or record read failed.

pub type FieldError {
  Missing(key: String)
  Invalid(reason: json.DecodeError)
  UnknownKeys(keys: List(String))
  SchemaMismatch(expected: Int, found: Int)
  WrongValueType(key: String, found: String)
  ReservedKey(key: String)
}

Missing(key: String)

A required field was absent.

Invalid(reason: json.DecodeError)

Stored JSON was malformed or did not have the expected type.

UnknownKeys(keys: List(String))

A sealed schema encountered undeclared keys.

SchemaMismatch(expected: Int, found: Int)

A versioned schema encountered a different stamped version.

WrongValueType(key: String, found: String)

A document entry did not contain an LWW register.

ReservedKey(key: String)

A field attempted to use the document's reserved clock key.

Prop

One record property, pairing a field with its record getter.

pub type Prop(a, b, c)

Schema

A bidirectional whole-record codec for a typed document.

pub type Schema(a, b)

SchemaError

Errors returned while configuring a schema.

pub type SchemaError {
  SealedKnownRequiresDeclaredKeys
}

SealedKnownRequiresDeclaredKeys

sealed_known needs a record1 through record9 schema so the declared keys are available.

WriteOp

One per-key operation produced by a whole-record encoder.

pub type WriteOp {
  Put(key: String, value: json.Json)
  Delete(key: String)
}

Put(key: String, value: json.Json)

Store a JSON value.

Delete(key: String)

Remove a key.

Constants

version_key

The reserved key used by versioned schemas.

pub const version_key: String

Functions

decode_entries

Decode a whole record from active document entries.

pub fn decode_entries(
  Schema(a, b),
  List(#(String, json.Json))
) -> Result(b, FieldError)

decode_optional

Decode an optional field value.

pub fn decode_optional(
  Field(a, b),
  option.Option(json.Json)
) -> Result(option.Option(b), FieldError)

decode_string

Decode a field directly from its JSON-string storage representation.

pub fn decode_string(
  Field(a, b),
  String
) -> Result(b, FieldError)

decode_value

Decode a field value from JSON.

pub fn decode_value(
  Field(a, b),
  json.Json
) -> Result(b, FieldError)

encode_ops

Encode a whole record as independent per-key operations.

pub fn encode_ops(
  Schema(a, b),
  b
) -> List(WriteOp)

encode_value

Encode a field value as JSON.

pub fn encode_value(
  Field(a, b),
  b
) -> json.Json

field

Define a typed field.

pub fn field(
  String,
  fn(a) -> json.Json,
  decode.Decoder(a)
) -> Field(b, a)

field_key

Return a field's storage key.

pub fn field_key(Field(a, b)) -> String

optional_prop

Define an optional record property.

None decodes from an absent key or JSON null and encodes as Delete.

pub fn optional_prop(
  Field(a, b),
  fn(c) -> option.Option(b)
) -> Prop(a, c, option.Option(b))

prop

Define a required record property.

pub fn prop(
  Field(a, b),
  fn(c) -> b
) -> Prop(a, c, b)

record1

Build a one-property record schema.

pub fn record1(
  fn(a) -> b,
  Prop(c, b, a)
) -> Schema(c, b)

record2

Build a two-property record schema.

pub fn record2(
  fn(a, b) -> c,
  Prop(d, c, a),
  Prop(d, c, b)
) -> Schema(d, c)

record3

Build a three-property record schema.

pub fn record3(
  fn(a, b, c) -> d,
  Prop(e, d, a),
  Prop(e, d, b),
  Prop(e, d, c)
) -> Schema(e, d)

record4

Build a four-property record schema.

pub fn record4(
  fn(a, b, c, d) -> e,
  Prop(f, e, a),
  Prop(f, e, b),
  Prop(f, e, c),
  Prop(f, e, d)
) -> Schema(f, e)

record5

Build a five-property record schema.

pub fn record5(
  fn(a, b, c, d, e) -> f,
  Prop(g, f, a),
  Prop(g, f, b),
  Prop(g, f, c),
  Prop(g, f, d),
  Prop(g, f, e)
) -> Schema(g, f)

record6

Build a six-property record schema.

pub fn record6(
  fn(a, b, c, d, e, f) -> g,
  Prop(h, g, a),
  Prop(h, g, b),
  Prop(h, g, c),
  Prop(h, g, d),
  Prop(h, g, e),
  Prop(h, g, f)
) -> Schema(h, g)

record7

Build a seven-property record schema.

pub fn record7(
  fn(a, b, c, d, e, f, g) -> h,
  Prop(i, h, a),
  Prop(i, h, b),
  Prop(i, h, c),
  Prop(i, h, d),
  Prop(i, h, e),
  Prop(i, h, f),
  Prop(i, h, g)
) -> Schema(i, h)

record8

Build an eight-property record schema.

pub fn record8(
  fn(a, b, c, d, e, f, g, h) -> i,
  Prop(j, i, a),
  Prop(j, i, b),
  Prop(j, i, c),
  Prop(j, i, d),
  Prop(j, i, e),
  Prop(j, i, f),
  Prop(j, i, g),
  Prop(j, i, h)
) -> Schema(j, i)

record9

Build a nine-property record schema.

pub fn record9(
  fn(a, b, c, d, e, f, g, h, i) -> j,
  Prop(k, j, a),
  Prop(k, j, b),
  Prop(k, j, c),
  Prop(k, j, d),
  Prop(k, j, e),
  Prop(k, j, f),
  Prop(k, j, g),
  Prop(k, j, h),
  Prop(k, j, i)
) -> Schema(k, j)

schema

Define an open, unversioned schema from hand-written codecs.

pub fn schema(
  decode.Decoder(a),
  fn(a) -> List(#(String, json.Json))
) -> Schema(b, a)

sealed

Restrict a schema to the supplied keys.

The reserved version_key remains permitted.

pub fn sealed(
  Schema(a, b),
  List(String)
) -> Schema(a, b)

sealed_known

Seal a record1 through record9 schema to its declared props.

Returns Error(SealedKnownRequiresDeclaredKeys) for a hand-written schema that has no declared keys; use sealed(schema, keys) there.

pub fn sealed_known(Schema(a, b)) -> Result(Schema(a, b), SchemaError)

stamp_entry

Return the version entry to write, if this schema is versioned.

pub fn stamp_entry(Schema(a, b)) -> option.Option(#(String, json.Json))

versioned

Attach an integer version checked by reads and written by stamp.

pub fn versioned(
  Schema(a, b),
  Int
) -> Schema(a, b)