From 1733a1accc37893fa9a9847485bd4f0ec945e3f1 Mon Sep 17 00:00:00 2001 From: cha0s Date: Tue, 26 Nov 2024 19:22:35 -0600 Subject: [PATCH] chore: doc --- README.md | 238 +++++++++++++++++++++++++++--------------------------- 1 file changed, 119 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index 415b1f5..636c0df 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,124 @@ const view = playerSchema.allocate(player); const written = playerSchema.encode(player, view); ``` +## Primitive types + +| Type Name | Bytes | Range of Values | +|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| bool (alias: boolean) | 1 (worst case, see [boolean coalescence](#boolean-coalescence)) | Truthy values are coerced to `true`; falsy values to `false` | +| int8 | 1 | -128 to 127 | +| uint8 | 1 | 0 to 255 | +| int16 | 2 | -32,768 to 32,767 | +| uint16 | 2 | 0 to 65,535 | +| int32 | 4 | -2,147,483,648 to 2,147,483,647 | +| uint32 | 4 | 0 to 4,294,967,295 | +| int64 | 8 | -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

**NOTE:** Only accepts and decodes to [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)s. | +| uint64 | 8 | 0 to 18,446,744,073,709,551,615

**NOTE:** Only accepts and decodes to [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)s. | +| float32 | 4 | 3.4E +/- 38 (7 digits) | +| float64 | 8 | 1.7E +/- 308 (15 digits) | +| string | [Prefix](#varuint-prefixes) followed by the [encoded](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/encodeInto) string bytes | Any string | +| buffer | [Prefix](#varuint-prefixes) followed by the bytes of the buffer | Any `ArrayBuffer`

**NOTE:** Decodes to a `DataView`.

See: [buffers and arrays](#buffers-and-arrays). | +| varuint |
sizeminmax
10127
212816,383
316,3842,097,151
42,097,152268,435,455
5268,435,45634,359,738,367
634,359,738,3684,398,046,511,103
74,398,046,511,104562,949,953,421,311
| 0 to 562,949,953,421,311 | +| varint |
sizeminmax
1-6463
2-8,1928,191
3-1,048,5761,048,575
4-134,217,728134,217,727
5-17,179,869,18417,179,869,183
6-2,199,023,255,5522,199,023,255,551
7-281,474,976,710,656281,474,976,710,655
| -281,474,976,710,656 to 281,474,976,710,655 | +| date | Same as `string` above after calling [`toIsoString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) | Value is coerced to `Date` e.g. `new Date(value).toIsoString()` | + +## Aggregate types + +### `object` + +Requires a `properties` key to define the properties on the object. Supports [`optional` fields](#optional-fields). Booleans are [coalesced](#boolean-coalescence). + +Example: + +```js +const schema = new Schema({ + type: 'object', + properties: { + foo: {type: 'uint32'}, + bar: {type: 'string', optional: true}, + }, +}); + +// 14 = uint32 (4) + optional flag (1) + string prefix (4) + 'hello' (5) +console.log(schema.size({foo: 32, bar: 'hello'})); +// 5 = uint32 (4) + optional flag (1) +console.log(schema.size({foo: 32})); +``` + +### `array` + +Requires an `element` key to define the structure of the array elements. Encodes a 32-bit prefix followed by the contents of the array. + +```js +const schema = new Schema({ + type: 'array', + element: {type: 'uint32'}, +}); + +// 16 = array prefix (4) + uint32 (4) + uint32 (4) + uint32 (4) +console.log(schema.size([1, 2, 3])); +``` + +Arrays of number types decode to [the corresponding `TypedArray`](#buffers-and-arrays). + +#### Fixed-length arrays + +Arrays may be specified as fixed-length through the `length` key. + +```js +const schema = new Schema({ + type: 'array', + element: {type: 'uint32'}, + length: 3, +}); + +// 12 = uint32 (4) + uint32 (4) + uint32 (4) +console.log(schema.size([1, 2, 3])); +``` + +No prefix is written, saving 4 bytes! + +### `map` + +Requires a `key` and `value` key to define the structure of the map. Any [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) will be coerced as [entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/Map#iterable). Encoded as an array of entries. Decodes to a native `Map` object. + +```js +const schema = new Schema({ + type: 'map', + key: {type: 'int32'}, + value: {type: 'string'}, +}); + +const value = new Map(); +value.set(32, 'sup'); +value.set(64, 'hi'); + +// 25 = array prefix (4) + int32 (4) + string prefix (4) + 'sup' (3) + int32 (4) + string prefix (4) + 'hi' (2) +console.log(schema.size(value)); +// same, with coercion +console.log(schema.size([[32, 'sup'], [64, 'hi']])); +``` + +### `set` + +Requires an `element` key to define the structure of the map. Any [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) will be coerced. Encoded as an array. Decodes to a native `Set` object. + +```js +const schema = new Schema({ + type: 'set', + element: {type: 'string'}, +}); + +const set = new Set(); +set.add('foo'); +set.add('bar'); + +// 18 = array prefix (4) + string prefix (4) + 'foo' (3) + string prefix (4) + 'bar' (3) +console.log(schema.size(set)); +// same, with coercion +console.log(schema.size(['foo', 'bar'])); +``` + ## :fire: features ### Boolean coalescence @@ -230,125 +348,7 @@ const schema = new Schema({ type: 'foobar', }); -console.log(schema.size()); // 1, because it's a bool. -``` - -## Primitive types - -| Type Name | Bytes | Range of Values | -|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| bool (alias: boolean) | 1 (worst case, see [boolean coalescence](#boolean-coalescence)) | Truthy values are coerced to `true`; falsy values to `false` | -| int8 | 1 | -128 to 127 | -| uint8 | 1 | 0 to 255 | -| int16 | 2 | -32,768 to 32,767 | -| uint16 | 2 | 0 to 65,535 | -| int32 | 4 | -2,147,483,648 to 2,147,483,647 | -| uint32 | 4 | 0 to 4,294,967,295 | -| int64 | 8 | -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

**NOTE:** Only accepts and decodes to [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)s. | -| uint64 | 8 | 0 to 18,446,744,073,709,551,615

**NOTE:** Only accepts and decodes to [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)s. | -| float32 | 4 | 3.4E +/- 38 (7 digits) | -| float64 | 8 | 1.7E +/- 308 (15 digits) | -| string | [Prefix](#varuint-prefixes) followed by the [encoded](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/encodeInto) string bytes | Any string | -| buffer | [Prefix](#varuint-prefixes) followed by the bytes of the buffer | Any `ArrayBuffer`

**NOTE:** Decodes to a `DataView`.

See: [buffers and arrays](#buffers-and-arrays). | -| varuint |
sizeminmax
10127
212816,383
316,3842,097,151
42,097,152268,435,455
5268,435,45634,359,738,367
634,359,738,3684,398,046,511,103
74,398,046,511,104562,949,953,421,311
| 0 to 562,949,953,421,311 | -| varint |
sizeminmax
1-6463
2-8,1928,191
3-1,048,5761,048,575
4-134,217,728134,217,727
5-17,179,869,18417,179,869,183
6-2,199,023,255,5522,199,023,255,551
7-281,474,976,710,656281,474,976,710,655
| -281,474,976,710,656 to 281,474,976,710,655 | -| date | Same as `string` above after calling [`toIsoString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) | Value is coerced to `Date` e.g. `new Date(value).toIsoString()` | - -## Aggregate types - -### `object` - -Requires a `properties` key to define the properties on the object. Supports [`optional` fields](#optional-fields). Booleans are [coalesced](#boolean-coalescence). - -Example: - -```js -const schema = new Schema({ - type: 'object', - properties: { - foo: {type: 'uint32'}, - bar: {type: 'string', optional: true}, - }, -}); - -// 14 = uint32 (4) + optional flag (1) + string prefix (4) + 'hello' (5) -console.log(schema.size({foo: 32, bar: 'hello'})); -// 5 = uint32 (4) + optional flag (1) -console.log(schema.size({foo: 32})); -``` - -### `array` - -Requires an `element` key to define the structure of the array elements. Encodes a 32-bit prefix followed by the contents of the array. - -```js -const schema = new Schema({ - type: 'array', - element: {type: 'uint32'}, -}); - -// 16 = array prefix (4) + uint32 (4) + uint32 (4) + uint32 (4) -console.log(schema.size([1, 2, 3])); -``` - -Arrays of number types decode to [the corresponding `TypedArray`](#buffers-and-arrays). - -#### Fixed-length arrays - -Arrays may be specified as fixed-length through the `length` key. - -```js -const schema = new Schema({ - type: 'array', - element: {type: 'uint32'}, - length: 3, -}); - -// 12 = uint32 (4) + uint32 (4) + uint32 (4) -console.log(schema.size([1, 2, 3])); -``` - -No prefix is written, saving 4 bytes! - -### `map` - -Requires a `key` and `value` key to define the structure of the map. Any [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) will be coerced as [entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/Map#iterable). Encoded as an array of entries. Decodes to a native `Map` object. - -```js -const schema = new Schema({ - type: 'map', - key: {type: 'int32'}, - value: {type: 'string'}, -}); - -const value = new Map(); -value.set(32, 'sup'); -value.set(64, 'hi'); - -// 25 = array prefix (4) + int32 (4) + string prefix (4) + 'sup' (3) + int32 (4) + string prefix (4) + 'hi' (2) -console.log(schema.size(value)); -// same, with coercion -console.log(schema.size([[32, 'sup'], [64, 'hi']])); -``` - -### `set` - -Requires an `element` key to define the structure of the map. Any [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) will be coerced. Encoded as an array. Decodes to a native `Set` object. - -```js -const schema = new Schema({ - type: 'set', - element: {type: 'string'}, -}); - -const set = new Set(); -set.add('foo'); -set.add('bar'); - -// 18 = array prefix (4) + string prefix (4) + 'foo' (3) + string prefix (4) + 'bar' (3) -console.log(schema.size(set)); -// same, with coercion -console.log(schema.size(['foo', 'bar'])); +console.log(schema.size()); // 1, because it's a bool ``` ## Motivation