🥮 mooncakes.io

lens

Typed JSON lenses, builders, and aggregate validation for MoonBit

json
lens
validation
moonbit
Download zip
Author
Version
0.4.3
License
MIT
Repository
Last updated
2 days ago
Downloads
656

#lens

totto2727/lens is a MoonBit module for typed JSON lenses, builders, and aggregate validation. The module publishes one lens package; see the detailed package README for checked examples and package-level usage.

This document is canonical README.mbt.md; maintain README.md as the relative symlink README.md -> README.mbt.md.

#Usage

Add the module, then follow the package usage examples.

moon add totto2727/lens@0.4.3

#Key features

  • One publishable lens package for typed JSON traversal and construction.
  • Checked package examples for typed reads and JSON object building.
  • Generated public API documentation on Mooncakes.

#Prerequisites

#Setup

  1. Add totto2727/lens to a MoonBit project.

moon add totto2727/lens@0.4.3

  1. Read the detailed package README for executable usage examples.

#API

The maintained public API index and generated signatures are published in the Mooncakes API reference.

#Development

For repository structure, validation commands, and contribution rules, see AGENTS.md.

#License

MIT. See LICENSE.

This README was generated from the share-artifact skill and README template.

#lens package

Detailed usage for the totto2727/lens package: typed JSON lenses, builders, and aggregate validation for reusable, checked access to JSON documents.

This document is the canonical literate package README; the repository module overview is ../README.mbt.md.

#Usage

Create typed child lenses once and reuse them across documents. A lens read reports a structured LensError with its JSON Pointer when traversal or decoding fails.

///|
test {
  let document = @json.parse("{\"user\":{\"name\":\"Ada\",\"age\":37}}")
  let user = object("user")
  let name_lens = user.string("name")
  let age_lens = user.int("age")

  inspect(name_lens.get(document), content="Ada")
  inspect(age_lens.get(document), content="37")
}

Build a new JSON object through the same typed lenses.

///|
test {
  let builder = JsonBuilder::JsonBuilder()
  let user = object("user")
  user.string("name").set(builder, "Ada")
  user.int("age").set(builder, 37)

  @json.json_inspect(builder, content={ "user": { "name": "Ada", "age": 37 } })
}

#Key features

  • Typed accessors for strings, booleans, numbers, integers, objects, arrays, custom FromJson/ToJson values, and raw Json.
  • Presence-aware reads and writes with distinct nullable, optional, and nullish semantics.
  • JsonBuilder construction with typed path-conflict errors and deterministic replacement/removal behavior.
  • Aggregate validate checks that preserve every failure in input order without constructing application values.
  • RFC 6901 pointers and standard JsonDecodeError path propagation for nested custom decoders.

#Prerequisites

#Setup

  1. Add the published module to a MoonBit project.

moon add totto2727/lens@0.4.3

  1. Import the package as @lens and compose lenses from @lens.root() or @lens.object("property").

#API

The maintained public API index and generated signatures are published in the Mooncakes API reference.

#Development

For repository structure, validation commands, and contribution rules, see AGENTS.md.

#License

MIT. See LICENSE.

This README was generated from the share-artifact skill and README template.

LensTrait

source
pub trait LensTrait {
  fn check(Self, Json) -> Unit raise LensError
}

A type-erased lens read used only for aggregate validation.

Implementations intentionally discard successful decoded values. Use the original typed lenses to read values after validate returns Valid.

JsonBuildError

source
pub suberror JsonBuildError {
  JsonBuildError(JsonBuildIssue)
} derive(Eq, 
Debug)

The typed error raised when a lens cannot write a value to a JSON builder.

LensError

source
pub suberror LensError {
  LensError(Issue)
} derive(Eq, 
Debug)

The typed error raised when a lens cannot read its selected value.

Decoder

source
type Decoder[T]

Encoder

source
type Encoder[T]

Issue

source
pub struct Issue {
  pointer : Pointer
  code : IssueCode
  message : String?
} derive(Eq, 
Debug)

A structured diagnostic containing the exact pointer and failure reason.

IssueCode

source
pub enum IssueCode {
  MissingProperty
  TypeMismatch(expected~ : JsonKind, actual~ : JsonKind)
  IndexOutOfBounds(index~ : Int, length~ : Int)
  ConstraintViolation(code~ : String)
  ExternalDecode
} derive(Eq, 
Debug)

A machine-readable reason why a lens or validation check failed.

JsonBuildIssue

source
pub struct JsonBuildIssue {
  pointer : Pointer
  code : JsonBuildIssueCode
} derive(Eq, 
Debug)

A structured JSON construction failure at an exact output pointer.

JsonBuildIssueCode

source
pub enum JsonBuildIssueCode {
  PathConflict
} derive(Eq, 
Debug)

A machine-readable reason why a typed value could not be written to a JSON builder.

JsonBuilder

source
pub struct JsonBuilder {
  // private fields
}

A mutable object builder populated through typed lenses and serialized with ToJson.

JsonBuilder::JsonBuilder

source
fn JsonBuilder::JsonBuilder() -> JsonBuilder

Creates an empty JSON object builder.

test {
  let builder = JsonBuilder::JsonBuilder()
  object("user").string("name").set(builder, "Ada")
  @json.json_inspect(builder, content={ "user": { "name": "Ada" } })
}

JsonKind

source
pub enum JsonKind {
  Null
  Boolean
  Number
  String
  Array
  Object
} derive(Eq, 
Debug)

The JSON value category used by structured lens diagnostics.

Lens

source
pub struct Lens[T] {
  // private fields
}

A reusable typed accessor for one location in a JSON document.

A lens can be reused across documents. Its selected pointer is retained in diagnostics, including nested array indices and RFC 6901 key escaping.
impl LensTrait for Lens[T]

Lens::add_to_json_path

source

Appends this lens's pointer to an existing JSON path.

Lens::array

source
fn[T] Lens::array(self : Lens[T]) -> Lens[Array[T]]

Returns a lens that decodes every array item with this lens's decoder.

Item failures include the zero-based item index in their diagnostic pointer.

Lens::decode_from_json

source

Selects raw JSON and delegates read-only decoding to standard FromJson.

Lens::get

source
fn[T] Lens::get(self : Lens[T], document : Json) -> T raise LensError

Reads and decodes this lens from a JSON document.

Lens::get_or_json_decode_error

source
fn[T] Lens::get_or_json_decode_error(self : Lens[T], document : Json, path : 
JsonPath) -> T raise 
JsonDecodeError

Reads this lens and translates a lens failure into a standard JSON decode error.

Lens::json_decode_error

source
fn[T] Lens::json_decode_error(self : Lens[T], path : 
JsonPath, message : String) -> 
JsonDecodeError

Creates a standard JSON decode error at this lens's location under an existing path.

Lens::nullable

source
fn[T] Lens::nullable(self : Lens[T]) -> PresenceLens[T]

Returns None for JSON null while preserving missing-property errors.

Lens::nullish

source
fn[T] Lens::nullish(self : Lens[T], encode_mode? : NullishEncodeMode) -> PresenceLens[T]

Returns None for either a missing selected path or JSON null.

None is omitted by default. Pass encode_mode=Null to write JSON null instead.

Lens::optional

source
fn[T] Lens::optional(self : Lens[T]) -> PresenceLens[T]

Returns None for a missing selected path while rejecting JSON null.

Lens::set

source
fn[T] Lens::set(self : Lens[T], builder : JsonBuilder, value : T) -> Unit raise JsonBuildError

Writes a typed value at this lens's output pointer.

Repeated writes to the same pointer use the latest value. Missing object parents are created. The builder is unchanged when a path conflict raises JsonBuildError.

Lens::set_or_abort

source
fn[T] Lens::set_or_abort(self : Lens[T], builder : JsonBuilder, value : T) -> Unit

Writes a typed value for an infallible serialization contract.

Use this from ToJson::to_json, whose trait signature cannot propagate JsonBuildError. A failure indicates a conflicting static output schema or another serializer implementation defect and aborts the process.

NullishEncodeMode

source
pub(all) enum NullishEncodeMode {
  Omit
  Null
} derive(Eq, 
Debug)

Controls how a nullish lens encodes None.

ObjectLens

source
pub struct ObjectLens {
  // private fields
}

A location in a JSON document from which typed child lenses can be created.

Reading an object returns a copied top-level map, so mutations to that map do not change the source document. Nested Json values retain normal JSON sharing semantics.

ObjectLens::bool

source
fn ObjectLens::bool(self : ObjectLens, key : String) -> Lens[Bool]

Returns a boolean lens positioned at a child property.

ObjectLens::custom

source
fn[T : 
FromJson + ToJson] ObjectLens::custom(self : ObjectLens, key : String) -> Lens[T]

Returns a typed lens that delegates decoding and encoding to standard JSON traits.

FromJson decode failures retain the selected JSON path, and ToJson supplies the corresponding builder encoding.

ObjectLens::get

source
fn ObjectLens::get(self : ObjectLens, document : Json) -> Map[String, Json] raise LensError

Reads this object lens from a JSON document.

ObjectLens::int

source
fn ObjectLens::int(self : ObjectLens, key : String) -> Lens[Int]

Returns an integer lens that delegates conversion to Double::to_int.

Fractional, saturating, and special-value behavior therefore follows the standard MoonBit Double::to_int conversion.

ObjectLens::json

source
fn ObjectLens::json(self : ObjectLens, key : String) -> Lens[Json]

Returns a raw JSON lens positioned at a child property.

Use this when the selected value intentionally remains opaque Json. For application types with standard JSON traits, prefer custom.

ObjectLens::number

source
fn ObjectLens::number(self : ObjectLens, key : String) -> Lens[Double]

Returns a number lens positioned at a child property.

The retained JSON Double is returned without an additional finiteness check, including non-finite values.

ObjectLens::object

source
fn ObjectLens::object(self : ObjectLens, key : String) -> ObjectLens

Returns an object lens positioned at a child property.

ObjectLens::string

source
fn ObjectLens::string(self : ObjectLens, key : String) -> Lens[String]

Returns a string lens positioned at a child property.

Pointer

source
pub struct Pointer {
  // private fields
} derive(Eq, 
Debug)

An immutable JSON Pointer identifying a location in a JSON document.

Pointer::to_string

source
fn Pointer::to_string(self : Pointer) -> String

Returns the RFC 6901 string representation of this pointer.

PresenceLens

source
pub struct PresenceLens[T] {
  // private fields
}

A typed accessor whose missing and null behavior can be replaced without nesting options.

Every presence combinator returns this same T? shape. The last combinator call controls both decoding and encoding behavior.

PresenceLens::add_to_json_path

source

Appends this lens's pointer to an existing JSON path.

PresenceLens::array

source
fn[T] PresenceLens::array(self : PresenceLens[T]) -> Lens[Array[T?]]

Returns a lens that treats every array item as nullable.

This normalizes None to JSON null so array indices remain stable. It is different from applying optional to the whole array property.

PresenceLens::get

source
fn[T] PresenceLens::get(self : PresenceLens[T], document : Json) -> T? raise LensError

Reads and decodes this presence-aware lens from a JSON document.

PresenceLens::get_or_json_decode_error

source

Reads this lens and translates a lens failure into a standard JSON decode error.

PresenceLens::json_decode_error

source

Creates a standard JSON decode error at this lens's location under an existing path.

PresenceLens::nullable

source
fn[T] PresenceLens::nullable(self : PresenceLens[T]) -> PresenceLens[T]

Replaces the current presence policy with nullable semantics.

PresenceLens::nullish

source
fn[T] PresenceLens::nullish(self : PresenceLens[T], encode_mode? : NullishEncodeMode) -> PresenceLens[T]

Replaces the current presence policy with nullish semantics.

PresenceLens::optional

source
fn[T] PresenceLens::optional(self : PresenceLens[T]) -> PresenceLens[T]

Replaces the current presence policy with optional semantics.

PresenceLens::set

source
fn[T] PresenceLens::set(self : PresenceLens[T], builder : JsonBuilder, value : T?) -> Unit raise JsonBuildError

Writes an optional typed value using this lens's current presence policy.

nullable(None) and nullish(encode_mode=Null) write JSON null, while optional(None) and nullish(encode_mode=Omit) remove the selected value.

PresenceLens::set_or_abort

source
fn[T] PresenceLens::set_or_abort(self : PresenceLens[T], builder : JsonBuilder, value : T?) -> Unit

Writes an optional typed value for an infallible serialization contract.

Validation

source
pub enum Validation {
  Valid
  Invalid(ReadOnlyArray[Issue])
} derive(Eq, 
Debug)

The outcome of validating a JSON document with type-erased checks.

Valid carries no decoded value. Use the original typed lenses to read the document after validation succeeds.

object

source
fn object(key : String) -> ObjectLens

Returns an object lens positioned at a root property.

root

source
fn root() -> ObjectLens

Returns an object lens positioned at the document root.

test {
  let document = @json.parse("{\"user\":{\"name\":\"Ada\"}}")
  inspect(object("user").string("name").get(document), content="Ada")
}

validate

source
fn validate(document : Json, lenses : Array[&LensTrait]) -> Validation

Runs every lens check and returns all issues in input order.

This function never constructs or returns application values. An empty input is Valid; otherwise every failed read is retained in the returned Invalid value.

test {
  let document = @json.parse("{\"user\":{\"name\":\"Ada\"}}")
  let name_lens = object("user").string("name")
  match validate(document, [name_lens]) {
    Valid => ()
    Invalid(_) => fail("expected valid document")
  }
}

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io