neco_gleam

# neco-gleam

[日本語](README-ja.md)

neco-gleam provides portable building blocks for Gleam programs. The package
covers diagnostic spans, byte input and output, deterministic JSON, and SHA-256
digests. Its pure Gleam implementation provides the same public behavior on the
Erlang and JavaScript targets.

## Requirements and dependencies

The package requires the following versions:

```toml
gleam = ">= 1.14.0"

[dependencies]
gleam_stdlib = ">= 1.0.0 and < 2.0.0"
```

## Features

- `neco_gleam/diagnostic`: half-open byte ranges with endpoint validation
- `neco_gleam/scanner`: byte reads and spans for consumed input
- `neco_gleam/printer`: output accumulation and completed byte sequences
- `neco_gleam/json`: JSON decoding and deterministic encoding
- `neco_gleam/digest`: SHA-256 calculation and hexadecimal rendering

JSON encoding recursively orders object fields by Unicode scalar value. It
preserves array order and JSON number spelling. Duplicate object keys produce a
typed encoding failure. Valid surrogate pairs decode as one Unicode scalar
value.

Operating-system integration belongs in packages with host-specific modules.

## Installation

```sh
gleam add neco_gleam
```

## Failure behavior

Operations with invalid input return a typed failure:

- `InvalidSpan`: a negative endpoint or a start greater than the end
- `InvalidBitSize`: SHA-256 input ending between byte boundaries
- scanner `Error(Nil)`: unavailable requested bytes
- JSON decoding failures: invalid UTF-8 or JSON, duplicate keys, excessive nesting, or trailing input
- `EncodeDuplicateKey`: duplicate object keys during JSON encoding

## License

MIT