From 5116871e349c2551adfc3c3bdfcd3791857e5d76 Mon Sep 17 00:00:00 2001 From: Iwo Plaza Date: Sun, 15 Sep 2024 16:23:26 +0200 Subject: [PATCH] Updated docs. --- .../content/docs/guides/arrays-and-tuples.mdx | 24 ++++----- .../content/docs/guides/getting-started.mdx | 16 +++--- .../src/content/docs/guides/objects.mdx | 52 ++++++++----------- .../src/content/docs/guides/optionals.mdx | 31 +++++------ .../content/docs/guides/primitive-values.mdx | 16 +++--- .../content/docs/guides/recursive-types.mdx | 29 ++++++----- .../serialization-and-deserialization.mdx | 42 +++++++-------- .../src/content/docs/guides/typed-arrays.mdx | 24 ++++----- packages/typed-binary/src/main-api.ts | 1 + 9 files changed, 112 insertions(+), 123 deletions(-) diff --git a/apps/typed-binary-docs/src/content/docs/guides/arrays-and-tuples.mdx b/apps/typed-binary-docs/src/content/docs/guides/arrays-and-tuples.mdx index 9225aef..957a11e 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/arrays-and-tuples.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/arrays-and-tuples.mdx @@ -8,11 +8,13 @@ description: A guide on how arrays and tuples can be represented in Typed Binary The items are encoded right next to each other. No need to store length information, as that is constant (built into the schema). ```ts -import { f32, arrayOf } from 'typed-binary'; +const Vector2 = bin.arrayOf(bin.f32, 2); +const Vector3 = bin.arrayOf(bin.f32, 3); +const Vector4 = bin.arrayOf(bin.f32, 4); -const Vector2 = arrayOf(f32, 2); -const Vector3 = arrayOf(f32, 3); -const Vector4 = arrayOf(f32, 4); +type Vector2 = bin.Parsed; // number[] +type Vector3 = bin.Parsed; // number[] +type Vector4 = bin.Parsed; // number[] ``` ## Dynamic Arrays @@ -20,9 +22,9 @@ const Vector4 = arrayOf(f32, 4); First 4 bytes of encoding are the length of the array, then its items next to one another. ```ts -import { i32, dynamicArrayOf } from 'typed-binary'; +const IntArray = bin.dynamicArrayOf(bin.i32); -const IntArray = dynamicArrayOf(i32); +type IntArray = bin.Parsed; // number[] ``` ## Tuple @@ -30,11 +32,9 @@ const IntArray = dynamicArrayOf(i32); Encodes an ordered set of schemas, one next to another. ```ts -import { f32, string, tupleOf } from 'typed-binary'; +const Vec3f = bin.tupleOf([bin.f32, bin.f32, bin.f32]); +type Vec3f = bin.Parsed; // [number, number, number] -const Vec3f = tupleOf([f32, f32, f32]); -type Vec3f = Parsed; // [number, number, number] - -const RecordEntry = tupleOf([string, Vec3f]); -type RecordEntry = Parsed; // [string, [number, number, number]] +const RecordEntry = bin.tupleOf([bin.string, Vec3f]); +type RecordEntry = bin.Parsed; // [string, [number, number, number]] ``` diff --git a/apps/typed-binary-docs/src/content/docs/guides/getting-started.mdx b/apps/typed-binary-docs/src/content/docs/guides/getting-started.mdx index d464a1a..d32baa1 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/getting-started.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/getting-started.mdx @@ -31,25 +31,25 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; ## Use in the browser ```ts {7} -import { tupleOf, f32, MaxValue, BufferWriter } from 'typed-binary'; +import bin from 'typed-binary'; // Define a schema -const Vec2f = tupleOf([f32, f32]); -const Vec2fSize = Vec2f.measure(MaxValue).size; +const Vec2f = bin.tupleOf([bin.f32, bin.f32]); +const Vec2fSize = Vec2f.measure(bin.MaxValue).size; const buffer = new ArrayBuffer(Vec2fSize); -Vec2f.write(new BufferWriter(buffer), [0.5, 3.14]); +Vec2f.write(new bin.BufferWriter(buffer), [0.5, 3.14]); ``` ## Use in Node.js ```ts {7} -import { tupleOf, f32, MaxValue, BufferWriter } from 'typed-binary'; +import bin from 'typed-binary'; // Define a schema -const Vec2f = tupleOf([f32, f32]); -const Vec2fSize = Vec2f.measure(MaxValue).size; +const Vec2f = bin.tupleOf([bin.f32, bin.f32]); +const Vec2fSize = Vec2f.measure(bin.MaxValue).size; const buffer = Buffer.alloc(Vec2fSize); -Vec2f.write(new BufferWriter(buffer), [0.5, 3.14]); +Vec2f.write(new bin.BufferWriter(buffer), [0.5, 3.14]); ``` \ No newline at end of file diff --git a/apps/typed-binary-docs/src/content/docs/guides/objects.mdx b/apps/typed-binary-docs/src/content/docs/guides/objects.mdx index 180956a..229e3d2 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/objects.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/objects.mdx @@ -4,18 +4,18 @@ description: Objects store their properties in key-ascending-alphabetical order, --- Primitive values in JavaScript can be composed into *Plain-Old-JavaScript-Objects*. This can be -easily represented using the `object()` schema constructor function. +easily represented using the `bin.object()` schema constructor function. ## Simple objects ```ts -import { i32, string, object } from 'typed-binary'; +import bin from 'typed-binary'; // Simple object schema -const Person = object({ - firstName: string, - lastName: string, - age: i32, +const Person = bin.object({ + firstName: bin.string, + lastName: bin.string, + age: bin.i32, }); // Writing a Person @@ -29,7 +29,7 @@ console.log(JSON.stringify(Person.read(reader))); // { "firstName": "John", ... ``` :::note -Objects store their properties in the order they are defined in the record passed into the `object()` constructor function. +Objects store their properties in the order they are defined in the record passed into the `bin.object()` constructor function. ::: ## Generic objects @@ -39,28 +39,22 @@ This feature allows for the parsing of a type that contains different fields dep ### Keyed by strings ```ts -import { - i32, - string, - bool, - generic, - object, -} from 'typed-binary'; +import bin from 'typed-binary'; // Generic object schema -const Animal = generic( +const Animal = bin.generic( { - nickname: string, - age: i32, + nickname: bin.string, + age: bin.i32, }, { - dog: object({ + dog: bin.object({ // Animal can be a dog - breed: string, + breed: bin.string, }), - cat: object({ + cat: bin.object({ // Animal can be a cat - striped: bool, + striped: bin.bool, }), } ); @@ -102,7 +96,7 @@ if (animal.type === 'cat') { ### Keyed by an enum (byte) ```ts -import { BufferWriter, BufferReader, i32, string, genericEnum, object } from 'typed-binary'; +import bin from 'typed-binary'; enum AnimalType = { DOG = 0, @@ -110,15 +104,15 @@ enum AnimalType = { }; // Generic (enum) object schema -const Animal = genericEnum({ - nickname: string, - age: i32, +const Animal = bin.genericEnum({ + nickname: bin.string, + age: bin.i32, }, { - [AnimalType.DOG]: object({ // Animal can be a dog - breed: string, + [AnimalType.DOG]: bin.object({ // Animal can be a dog + breed: bin.string, }), - [AnimalType.CAT]: object({ // Animal can be a cat - striped: bool, + [AnimalType.CAT]: bin.object({ // Animal can be a cat + striped: bin.bool, }), }); diff --git a/apps/typed-binary-docs/src/content/docs/guides/optionals.mdx b/apps/typed-binary-docs/src/content/docs/guides/optionals.mdx index fb382bd..ad4f444 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/optionals.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/optionals.mdx @@ -11,32 +11,25 @@ They are encoded as: - `1 encoded(value)` given `value !== undefined`. ```ts -import { - BufferWriter, - BufferReader, - i32, - string, - object, - optional, -} from 'typed-binary'; +import bin from 'typed-binary'; const buffer = Buffer.alloc(16); -const writer = new BufferWriter(buffer); -const reader = new BufferReader(buffer); +const writer = new bin.BufferWriter(buffer); +const reader = new bin.BufferReader(buffer); // Simple object schema -const Address = object({ - city: string, - street: string, - postalCode: string, +const Address = bin.object({ + city: bin.string, + street: bin.string, + postalCode: bin.string, }); // Simple object schema (with optional field) -const Person = object({ - firstName: string, - lastName: string, - age: i32, - address: optional(Address), +const Person = bin.object({ + firstName: bin.string, + lastName: bin.string, + age: bin.i32, + address: bin.optional(Address), }); // Writing a Person (no address) diff --git a/apps/typed-binary-docs/src/content/docs/guides/primitive-values.mdx b/apps/typed-binary-docs/src/content/docs/guides/primitive-values.mdx index 6e345a6..cc244c9 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/primitive-values.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/primitive-values.mdx @@ -17,17 +17,17 @@ There are a few primitives to choose from: - A string of characters followed by a `\0` terminal character. ```ts -import { BufferWriter, BufferReader, byte, string } from 'typed-binary'; +import bin from 'typed-binary'; const buffer = Buffer.alloc(16); // Writing four bytes into the buffer -const writer = new BufferWriter(buffer); -byte.write(writer, 'W'.charCodeAt(0)); -byte.write(writer, 'o'.charCodeAt(0)); -byte.write(writer, 'w'.charCodeAt(0)); -byte.write(writer, 0); +const writer = new bin.BufferWriter(buffer); +bin.byte.write(writer, 'W'.charCodeAt(0)); +bin.byte.write(writer, 'o'.charCodeAt(0)); +bin.byte.write(writer, 'w'.charCodeAt(0)); +bin.byte.write(writer, 0); -const reader = new BufferReader(buffer); -console.log(string.read(reader)); // > Wow +const reader = new bin.BufferReader(buffer); +console.log(bin.string.read(reader)); // > Wow ``` diff --git a/apps/typed-binary-docs/src/content/docs/guides/recursive-types.mdx b/apps/typed-binary-docs/src/content/docs/guides/recursive-types.mdx index 3cfb92b..89d74bf 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/recursive-types.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/recursive-types.mdx @@ -7,7 +7,7 @@ If you want an object type to be able to contain one of itself (recursion), then ```ts /** - * Wrapping a schema with a 'keyed' call allows the inner code to + * Wrapping a schema with a 'bin.keyed' call allows the inner code to * use a reference to the type we're currently creating, instead * of the type itself. * @@ -21,10 +21,10 @@ If you want an object type to be able to contain one of itself (recursion), then * This is because references are resolved recursively once the method * passed as the 2nd argument to 'keyed' returns the schema. */ -const Recursive = keyed('recursive-key', (Recursive) => - object({ - value: i32, - next: optional(Recursive), +const Recursive = bin.keyed('recursive-key', (Recursive) => + bin.object({ + value: bin.i32, + next: bin.optional(Recursive), }) ); ``` @@ -32,28 +32,29 @@ const Recursive = keyed('recursive-key', (Recursive) => ### Recursive types alongside generics ```ts -import { i32, string, object, keyed } from 'typed-binary'; +import bin from 'typed-binary'; -type Expression = Parsed; -const Expression = keyed('expression', (Expression) => - generic( +const Expression = bin.keyed('expression', (Expression) => + bin.generic( {}, { - multiply: object({ + multiply: bin.object({ a: Expression, b: Expression, }), - negate: object({ + negate: bin.object({ inner: Expression, }), - int_literal: object({ - value: i32, + int_literal: bin.object({ + value: bin.i32, }), } ) ); -const expr: Parsed = { +type Expression = bin.Parsed; + +const expr: Expression = { type: 'multiply', a: { type: 'negate', diff --git a/apps/typed-binary-docs/src/content/docs/guides/serialization-and-deserialization.mdx b/apps/typed-binary-docs/src/content/docs/guides/serialization-and-deserialization.mdx index 67adb85..e504f88 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/serialization-and-deserialization.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/serialization-and-deserialization.mdx @@ -25,20 +25,20 @@ measure(value: T | MaxValue, measurer: IMeasurer): IMeasurer; The `ISerialInput/Output` interfaces have a basic built-in implementation that reads/writes to a buffer: ```ts -import { BufferReader, BufferWriter, byte, string } from 'typed-binary'; +import bin from 'typed-binary'; // Creating a fixed-length buffer of arbitrary size (64 bytes). const buffer = Buffer.alloc(64); // Or new ArrayBuffer(64); on browsers. // Writing four bytes into the buffer -const writer = new BufferWriter(buffer); // Implements ISerialOutput -byte.write(writer, 'W'.charCodeAt(0)); -byte.write(writer, 'o'.charCodeAt(0)); -byte.write(writer, 'w'.charCodeAt(0)); -byte.write(writer, 0); - -const reader = new BufferReader(buffer); // Implements ISerialInput -console.log(string.read(reader)); // > Wow +const writer = new bin.BufferWriter(buffer); // Implements ISerialOutput +bin.byte.write(writer, 'W'.charCodeAt(0)); +bin.byte.write(writer, 'o'.charCodeAt(0)); +bin.byte.write(writer, 'w'.charCodeAt(0)); +bin.byte.write(writer, 0); + +const reader = new bin.BufferReader(buffer); // Implements ISerialInput +console.log(bin.string.read(reader)); // > Wow ``` ### Creating a buffer with the most optimal size @@ -47,12 +47,12 @@ Schemas can measure how many bytes a particular value will take up, which can be to create a buffer that will fit that value perfectly. ```ts -import { object, u32, f32 } from 'typed-binary'; +import bin from 'typed-binary'; -export const PlayerUpdatePacket = object({ - id: u32, - x: f32, - y: f32, +export const PlayerUpdatePacket = bin.object({ + id: bin.u32, + x: bin.f32, + y: bin.f32, }); const packet = { @@ -70,15 +70,15 @@ const buffer = Buffer.alloc(packetSize); // or new ArrayBuffer(packetSize) on th If a schema's size is bounded (there is a max size that no value encodings will surpass), we can create a shared buffer of the maximum size the schema can take. -```ts "MaxValue" -import { object, u32, f32, MaxValue } from 'typed-binary'; +```ts "bin.MaxValue" +import bin from 'typed-binary'; -export const PlayerUpdatePacket = object({ - id: u32, - x: f32, - y: f32, +export const PlayerUpdatePacket = bin.object({ + id: bin.u32, + x: bin.f32, + y: bin.f32, }); -const maxPacketSize = PlayerUpdatePacket.measure(MaxValue).size; +const maxPacketSize = PlayerUpdatePacket.measure(bin.MaxValue).size; const sharedBuffer = Buffer.alloc(maxPacketSize); // or new ArrayBuffer(maxPacketSize) on the browser ``` diff --git a/apps/typed-binary-docs/src/content/docs/guides/typed-arrays.mdx b/apps/typed-binary-docs/src/content/docs/guides/typed-arrays.mdx index e78d21d..dac9a06 100644 --- a/apps/typed-binary-docs/src/content/docs/guides/typed-arrays.mdx +++ b/apps/typed-binary-docs/src/content/docs/guides/typed-arrays.mdx @@ -7,9 +7,9 @@ Sometimes binary is the format that we want to work with directly. [Typed array] allow that data to be nested in plain objects or arrays. ```ts -const Image = object({ - size: tupleOf([u32, u32]), - bitmap: u8Array(256 * 256), +const Image = bin.object({ + size: bin.tupleOf([bin.u32, bin.u32]), + bitmap: bin.u8Array(256 * 256), }); // { @@ -26,12 +26,12 @@ Below is the list of available typed array schemas. Schema constructor | Encoded as | JavaScript value ---|---|--- -`u8Array` | consecutive 8-bit unsigned integers | `Uint8Array` -`u8ClampedArray` | consecutive 8-bit unsigned integers | `Uint8ClampedArray` -`u16Array` | consecutive 16-bit unsigned integers | `Uint16Array` -`u32Array` | consecutive 32-bit unsigned integers | `Uint32Array` -`i8Array` | consecutive 8-bit signed integers | `Int8Array` -`i16Array` | consecutive 16-bit signed integers | `Int16Array` -`i32Array` | consecutive 32-bit signed integers | `Int32Array` -`f32Array` | consecutive 32-bit floats | `Float32Array` -`f64Array` | consecutive 64-bit floats | `Float64Array` +`bin.u8Array` | consecutive 8-bit unsigned integers | `Uint8Array` +`bin.u8ClampedArray` | consecutive 8-bit unsigned integers | `Uint8ClampedArray` +`bin.u16Array` | consecutive 16-bit unsigned integers | `Uint16Array` +`bin.u32Array` | consecutive 32-bit unsigned integers | `Uint32Array` +`bin.i8Array` | consecutive 8-bit signed integers | `Int8Array` +`bin.i16Array` | consecutive 16-bit signed integers | `Int16Array` +`bin.i32Array` | consecutive 32-bit signed integers | `Int32Array` +`bin.f32Array` | consecutive 32-bit floats | `Float32Array` +`bin.f64Array` | consecutive 64-bit floats | `Float64Array` diff --git a/packages/typed-binary/src/main-api.ts b/packages/typed-binary/src/main-api.ts index 59adeda..169c045 100644 --- a/packages/typed-binary/src/main-api.ts +++ b/packages/typed-binary/src/main-api.ts @@ -1,3 +1,4 @@ +export { MaxValue } from './structure'; export * from './describe'; export * from './io'; export * from './error';