# gizlang/wire

Typed values as bytes on a wire: the one format that programs, hosts and peers built from the same source use to talk. The type is the schema. A record is its fields in order, with no names; a number is 8 bytes little-endian; a bool one byte; a string, bytes, Vec or Map a u32 count and then its items; an Option a byte (0 none, 1 some) and its value; a union's case its index as one byte and then its fields. Each type writes and reads itself: here the scalars and the containers, and the compiler gives each record and union its own (checker derivedMethod), from the helpers below. Json, a union, is written so too.

A program that reads the bytes in another language (a page's JavaScript: app/components/src/wire.js) takes the type's schema: `schema<T>()` is its fields and cases as JSON text, which the compiler writes for each record and union too.

JSON stays the codec for what a person or an outside API reads: `encode(value, "json")` writes gizlang/json's text of the same value, and `decode` reads it back.

```gizlang
import * as Wire from "gizlang/wire";
```

## Types

### `WireError`

```gizlang
type WireError = { offset: i64; message: string; }
```

Where the bytes stop being a T.

- `offset`: `i64`
- `message`: `string`

### `Reader`

```gizlang
type Reader = { data: bytes; at: i64; }
```

Bytes being read, from AT.

- `data`: `bytes`
- `at`: `i64`

### `Codec`

```gizlang
type Codec = "wire" | "json"
```

How a value is written: "wire", the compact binary form (the default and the fastest), or "json", text that a person
or an outside API reads.

### `SchemaField`

```gizlang
type SchemaField = { name: string; type: string; }
```

One field of a schema's type: its name and its type (SchemaType.fields).

- `name`: `string`
- `type`: `string`

### `SchemaCase`

```gizlang
type SchemaCase = { kind: string; fields: Vec<SchemaField>; }
```

One case of a union, or a record's one case (KIND "").

- `kind`: `string`
- `fields`: `Vec<gizlang_wire.SchemaField>`

### `SchemaType`

```gizlang
type SchemaType = { name: string; union: bool; cases: Vec<SchemaCase>; }
```

- `name`: `string`
- `union`: `bool`
- `cases`: `Vec<gizlang_wire.SchemaCase>`

### `Schema`

```gizlang
type Schema = { keys: Map<string, i64>; types: Vec<SchemaType>; open: Vec<i64>; refs: Vec<string>; }
```

A schema being written (schema). A type is a name ("f64", "i64", "u64", "bool", "string", "bytes"), {"vec": T},
{"option": T}, {"map": [K, V]}, or the index of a record or union in TYPES.

- `keys`: `_gizlang_sdk_collections.Map<string, i64>`
- `types`: `Vec<gizlang_wire.SchemaType>`
- `open`: `Vec<i64>`
- `refs`: `Vec<string>`

## Functions

### `encode`

```gizlang
function encode<T>(value: T, codec: Codec = "wire"): bytes
```

VALUE as bytes in CODEC.

### `decode`

```gizlang
function decode<T>(data: bytes, codec: Codec = "wire"): T throws WireError
```

DATA as a T, as encode wrote it in CODEC. Bytes that end early, or run past the value, are an error.

### `schema`

```gizlang
function schema<T>(): string
```

T's wire schema as JSON: `{"root": type, "types": [{"name", "fields": [[name, type], ...]} or {"name", "cases":
[[kind, [[name, type], ...]], ...]}, ...]}`. An untagged union's cases have the kind "" and one unnamed field.

### `schemaOpen`

```gizlang
function schemaOpen(out: mut Schema, key: string, name: string): bool
```

Starts the type KEY, named NAME, and whether it is new: a type met before (or being written) is its index alone.

Effects: fail, alloc.

### `schemaCase`

```gizlang
function schemaCase(out: mut Schema, kind: string): bool
```

Starts a union's case KIND; true, so a derived writeSchema writes the case's fields in its own scope.

Effects: fail, alloc.

### `schemaField`

```gizlang
function schemaField<T>(out: mut Schema, name: string, value: T): void
```

Adds the field NAME of VALUE's type to the open type's last case.

### `schemaEnd`

```gizlang
function schemaEnd(out: mut Schema): void
```

Ends the open type.

Effects: fail, alloc.

### `expectReader`

```gizlang
function expectReader(input: mut Reader): void throws WireError
```

Gives a derived readWire its types; reads nothing.

Effects: fail.

### `writeTag`

```gizlang
function writeTag(out: mut bytes, index: i64): void
```

Writes a union's case INDEX.

Effects: fail, alloc.

### `writeValue`

```gizlang
function writeValue<T>(out: mut bytes, value: T): void
```

Writes VALUE, an untagged union's case, as its own type does.

### `readTag`

```gizlang
function readTag(input: mut Reader): i64 throws WireError
```

Reads a union's case index.

Effects: fail.

### `unknownTag`

```gizlang
function unknownTag(tag: i64): void throws WireError
```

The error of a case index TAG that the union does not have.

Effects: fail, alloc.

## Methods

### `f64.writeSchema`

```gizlang
function f64.writeSchema(self: f64, out: mut Schema): void
```

Effects: fail, alloc.

### `i64.writeSchema`

```gizlang
function i64.writeSchema(self: i64, out: mut Schema): void
```

Effects: fail, alloc.

### `u64.writeSchema`

```gizlang
function u64.writeSchema(self: u64, out: mut Schema): void
```

Effects: fail, alloc.

### `bool.writeSchema`

```gizlang
function bool.writeSchema(self: bool, out: mut Schema): void
```

Effects: fail, alloc.

### `string.writeSchema`

```gizlang
function string.writeSchema(self: string, out: mut Schema): void
```

Effects: fail, alloc.

### `bytes.writeSchema`

```gizlang
function bytes.writeSchema(self: bytes, out: mut Schema): void
```

Effects: fail, alloc.

### `Vec.writeSchema`

```gizlang
function Vec.writeSchema<T>(self: Vec<T>, out: mut Schema): void
```

### `Option.writeSchema`

```gizlang
function Option.writeSchema<T>(self: Option<T>, out: mut Schema): void
```

### `Map.writeSchema`

```gizlang
function Map.writeSchema<K, V>(self: Map<K, V>, out: mut Schema): void
```

### `f64.writeWire`

```gizlang
function f64.writeWire(self: f64, out: mut bytes): void
```

Writes the number: 8 bytes, little-endian.

Effects: fail, alloc.

### `i64.writeWire`

```gizlang
function i64.writeWire(self: i64, out: mut bytes): void
```

Writes the integer: 8 bytes, little-endian.

Effects: fail, alloc.

### `u64.writeWire`

```gizlang
function u64.writeWire(self: u64, out: mut bytes): void
```

Writes the integer: 8 bytes, little-endian.

Effects: fail, alloc.

### `bool.writeWire`

```gizlang
function bool.writeWire(self: bool, out: mut bytes): void
```

Writes the boolean: one byte.

Effects: fail, alloc.

### `string.writeWire`

```gizlang
function string.writeWire(self: string, out: mut bytes): void
```

Writes the string: its UTF-8 length as a u32, then its bytes.

Effects: fail, alloc.

### `bytes.writeWire`

```gizlang
function bytes.writeWire(self: bytes, out: mut bytes): void
```

Writes the bytes: their length as a u32, then them.

Effects: fail, alloc.

### `Vec.writeWire`

```gizlang
function Vec.writeWire<T>(self: Vec<T>, out: mut bytes): void
```

Writes the vector: its length as a u32, then each item.

### `Option.writeWire`

```gizlang
function Option.writeWire<T>(self: Option<T>, out: mut bytes): void
```

Writes 0 for none, else 1 and the value.

### `Map.writeWire`

```gizlang
function Map.writeWire<K, V>(self: Map<K, V>, out: mut bytes): void
```

Writes the map: its size as a u32, then each key and value.

### `f64.readWire`

```gizlang
function f64.readWire(self: mut f64, input: mut Reader): void throws WireError
```

Reads a number.

Effects: fail.

### `i64.readWire`

```gizlang
function i64.readWire(self: mut i64, input: mut Reader): void throws WireError
```

Reads an integer.

Effects: fail.

### `u64.readWire`

```gizlang
function u64.readWire(self: mut u64, input: mut Reader): void throws WireError
```

Reads an integer.

Effects: fail.

### `bool.readWire`

```gizlang
function bool.readWire(self: mut bool, input: mut Reader): void throws WireError
```

Reads a boolean; a byte other than 0 or 1 is an error.

Effects: fail.

### `string.readWire`

```gizlang
function string.readWire(self: mut string, input: mut Reader): void throws WireError
```

Reads a string; bytes that are not UTF-8 are an error.

Effects: fail, alloc.

### `bytes.readWire`

```gizlang
function bytes.readWire(self: mut bytes, input: mut Reader): void throws WireError
```

Reads bytes.

Effects: fail, alloc.

### `Vec.readWire`

```gizlang
function Vec.readWire<T>(self: mut Vec<T>, input: mut Reader): void throws WireError
```

Reads a vector, each item as T.

### `Option.readWire`

```gizlang
function Option.readWire<T>(self: mut Option<T>, input: mut Reader): void throws WireError
```

Reads 0 as none, and 1 and a T as the value.

### `Map.readWire`

```gizlang
function Map.readWire<K, V>(self: mut Map<K, V>, input: mut Reader): void throws WireError
```

Reads a map, each key as K and each value as V.

