Skip to content

Commit

Permalink
Updated docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
iwoplaza committed Sep 15, 2024
1 parent 6e680cd commit 5116871
Show file tree
Hide file tree
Showing 9 changed files with 112 additions and 123 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -8,33 +8,33 @@ 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<typeof Vector2>; // number[]
type Vector3 = bin.Parsed<typeof Vector3>; // number[]
type Vector4 = bin.Parsed<typeof Vector4>; // number[]
```

## Dynamic Arrays

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<typeof IntArray>; // number[]
```

## Tuple

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<typeof Vec3f>; // [number, number, number]

const Vec3f = tupleOf([f32, f32, f32]);
type Vec3f = Parsed<typeof Vec3f>; // [number, number, number]

const RecordEntry = tupleOf([string, Vec3f]);
type RecordEntry = Parsed<typeof RecordEntry>; // [string, [number, number, number]]
const RecordEntry = bin.tupleOf([bin.string, Vec3f]);
type RecordEntry = bin.Parsed<typeof RecordEntry>; // [string, [number, number, number]]
```
Original file line number Diff line number Diff line change
Expand Up @@ -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]);
```
52 changes: 23 additions & 29 deletions apps/typed-binary-docs/src/content/docs/guides/objects.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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,
}),
}
);
Expand Down Expand Up @@ -102,23 +96,23 @@ 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,
CAT = 1,
};

// 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,
}),
});

Expand Down
31 changes: 12 additions & 19 deletions apps/typed-binary-docs/src/content/docs/guides/optionals.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
29 changes: 15 additions & 14 deletions apps/typed-binary-docs/src/content/docs/guides/recursive-types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -21,39 +21,40 @@ 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),
})
);
```

### Recursive types alongside generics

```ts
import { i32, string, object, keyed } from 'typed-binary';
import bin from 'typed-binary';

type Expression = Parsed<typeof Expression>;
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<typeof Expression> = {
type Expression = bin.Parsed<typeof Expression>;

const expr: Expression = {
type: 'multiply',
a: {
type: 'negate',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 = {
Expand All @@ -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
```
Loading

0 comments on commit 5116871

Please sign in to comment.