Update README.md

Author: robertwayne

README.md

@@ -2,27 +2,29 @@
 
 bufferfish is utility library for working with binary network messages between Rust and TypeScript, such as over WebSockets. It provides a simple API for encoding and decoding data into binary arrays, as well as generating TypeScript definitions and decoding functions from your Rust code.
 
-_This library has an unstable API and is missing a variety of functionality. I can't recommend using it in production, although I am using it for my own production project._
+_This library has an unstable API and may be missing some basic functionality. I can't recommend using it in production, although I am using it for my own production project._
 
 ## Repository Overview
 
 There are two seperate libraries in this repo: one for Rust and one for TypeScript. Neither of the libraries have any required dependencies. The Rust version optionally uses the `unicode-width` crate for formatting buffer output when `pretty-print` is enabled.
 
 The Rust library is broken into three seperate crates:
 
-### /bufferfish
+### /rust/bufferfish
 
 `bufferfish` is a re-export of the other crates, as well as a `generate` function for use in `build.rs` files in order to generate TypeScript definitions from your Rust packet ID type. This is what users will interact with directly. General tests also live here.
 
-### /bufferfish-derive
+### /rust/bufferfish-derive
 
 `bufferfish_derive` is where the proc macro code for the `#[derive(Encode)]` and `#[derive(Decode)]` macros live. These annotations implement `Encodable` and `Decodable` - respectively - for the annotated type.
 
-### /bufferfish-core
+### /rust/bufferfish-core
 
 `bufferfish_core`is the primary library implementation. Trait and type definitions, byte and cursor logic, and error handling live here.
 
-TypeScript code lives alone within the `/typescript` directory.
+### /typescript/bufferfish
+
+The TypeScript implementation lives here. The API is generally mirrored from the Rust version.
 
 ## Examples
 
@@ -90,7 +92,7 @@ async fn process(steam: TcpStream) -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-# Decoding Generated Packets
+### Using Generated Decoding Functions (JavaScript)
 
 These are built when defining a struct or enum in Rust with the `#[derive(Encode)]` macro after calling the `bufferfish::generate()` function.
 
@@ -110,7 +112,7 @@ ws.onmessage = (event) => {
 }
 ```
 
-## Manually Decoding Packets
+### Manually Decoding a Bufferfish (JavaScript)
 
 ```typescript
 const ws = new WebSocket("ws://127.0.0.1:3000")
@@ -147,7 +149,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-### Example Generation
+### Codegen Example
 
 ```rust
 use bufferfish::Encode;
@@ -204,7 +206,7 @@ export const decodeJoinPacket = (bf: Bufferfish): JoinPacket => {
 }
 ```
 
-## Encodable Types
+## Encodable / Decodable Types
 
 Supported Types             | Decodes As
 --------------------------- | ---------------------
@@ -219,9 +221,11 @@ Supported Types             | Decodes As
 `Vec<T> where T: Encodable` | `Array<T>`
 `T where T: Encodable`      | `object` or primitive
 
+_*The reverse is true for decoding._
+
 ## Notes
 
-- I strongly recommend the usage of the [num_enum](https://github.com/illicitonion/num_enum) crate for deriving `IntoPrimitive` and `FromPrimitve` on your packet ID enum. This removes a lot of boilerplate.
+- I recommend using the [num_enum](https://github.com/illicitonion/num_enum) crate for deriving `IntoPrimitive` and `FromPrimitve` on enums you wish to `Encode`. This removes a lot of boilerplate.
 - Enums in TypeScript are often mentioned as a "bad" feature, and this is generally true when considering typical web development use-cases. In the case of a list of "op codes" mapping to dev-friendly names, however, they are actually really useful. Modern bundlers - like `esbuild` - [can actually inline them, meaning we just get integer literals in the final output.](https://sombia.com/posts/typescript-enums).
 
 ## Security
@@ -232,6 +236,10 @@ When reading data, you will always get the correct return type - however, you ar
 
 This kind of problem should be dealt with before operating on the buffer.
 
+Decoding an oversized bufferfish via the `Decode` trait will just ignore / discard the additional data, as it is only going to read specific byte lengths generated by the `Encodable` impl.
+
+Decoding an undersized bufferfish will return a `BufferfishError::FailedWrite`.
+
 ## Contributing
 
 `bufferfish` is open to contributions, however it should be noted that the library was created for my own game projects, and I am not interested in making it widely general-purpose. If you have a feature request or bug fix that you think would be useful to others, feel free to open an issue or PR either way.

rust/bufferfish-core/README.md

@@ -2,8 +2,6 @@
 
 Core types, traits, and logic implementations for [bufferfish](https://github.com/robertwayne/bufferfish).
 
-_This project has an unstable API and is missing a variety of functionality. I can't recommend using it in production, although I am using it for my own production project._
-
 ## Usage
 
 See the [main project repository](https://github.com/robertwayne/bufferfish) for more details.

rust/bufferfish-derive/README.md

@@ -2,8 +2,6 @@
 
 Macros for [bufferfish](https://github.com/robertwayne/bufferfish).
 
-_This project has an unstable API and is missing a variety of functionality. I can't recommend using it in production, although I am using it for my own production project._
-
 ## Usage
 
 See the [main project repository](https://github.com/robertwayne/bufferfish) for more details.

rust/bufferfish/README.md

@@ -2,7 +2,7 @@
 
 `bufferfish` is utility library for working with binary network messages between Rust and TypeScript, such as over WebSockets. It provides a simple API for encoding and decoding data into binary arrays, as well as generating TypeScript definitions and decoding functions from your Rust code.
 
-_This library has an unstable API and is missing a variety of functionality. I can't recommend using it in production, although I am using it for my own production project._
+_This library has an unstable API and may be missing some basic functionality. I can't recommend using it in production, although I am using it for my own production project._
 
 ## Examples
 
@@ -70,7 +70,7 @@ async fn process(steam: TcpStream) -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-### Using Generated Packet Readers
+### Using Generated Decoding Functions (JavaScript)
 
 ```typescript
 const ws = new WebSocket("ws://127.0.0.1:3000")
@@ -88,7 +88,7 @@ ws.onmessage = (event) => {
 }
 ```
 
-### Manually Reading Packets
+### Manually Decoding a Bufferfish (JavaScript)
 
 ```typescript
 const ws = new WebSocket("ws://127.0.0.1:3000")
@@ -125,7 +125,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-### Example Generation
+### Codegen Example
 
 ```rust
 use bufferfish::Encode;
@@ -171,7 +171,7 @@ export const decodeJoinPacket = (bf: Bufferfish): JoinPacket => {
 }
 ```
 
-## Encodable Types
+# Encodable / Decodable Types
 
 Supported Types             | Decodes As
 --------------------------- | ---------------------
@@ -186,19 +186,25 @@ Supported Types             | Decodes As
 `Vec<T> where T: Encodable` | `Array<T>`
 `T where T: Encodable`      | `object` or primitive
 
+_*The reverse is true for decoding._
+
 ## Notes
 
-- I strongly recommend the usage of the [num_enum](https://github.com/illicitonion/num_enum) crate for deriving `IntoPrimitive` and `FromPrimitve` on your packet ID enum. This removes a lot of boilerplate.
-- Enums in TypeScript are often mentioned as a "bad" feature, and this is generally true when considering typical web development use-cases. In the case of a list of "op codes" mapping to dev-friendly names, however, they are actually really useful. Modern bundlers - like `esbuild` - [can actually inline them, meaning we just get integer literals in the final output.](https://sombia.com/posts/typescript-enums).
+- I recommend using the [num_enum](https://github.com/illicitonion/num_enum) crate for deriving `IntoPrimitive` and `FromPrimitve` on enums you wish to `Encode`. This removes a lot of boilerplate.
+- Enums in TypeScript are often mentioned as a "bad" feature, and this is generally true when considering typical web development use-cases. In the case of a list of "op codes", mapping to dev-friendly names, however, they are actually really useful. Modern bundlers - like `esbuild` - [can actually inline them, meaning we just get integer literals in the final output.](https://sombia.com/posts/typescript-enums).
 
-## Security
+# Security
 
 `bufferfish` functions ensure inputs are valid as a "best effort". Internal buffers are constructed with a maximum capacity _(default of 1024 bytes)_, and will fail to construct if an input would cause the internal buffer to cross that threshold.
 
 When reading data, you will always get the correct return type - however, you are still subject to corrupted data if the input was incorrect but technically valid. For example, if you call `read_u8` on a buffer that contains a `u16` at the cursor position, you will get a `u8` back, as the buffer has no way to know that it was originally encoded as a `u16`. It is valid data, but will very likely be an unexpected value.
 
 This kind of problem should be dealt with before operating on the buffer.
 
+Decoding an oversized bufferfish via the `Decode` trait will just ignore / discard the additional data, as it is only going to read specific byte lengths generated by the `Encodable` impl.
+
+Decoding an undersized bufferfish will return a `BufferfishError::FailedWrite`.
+
 ## Contributing
 
 `bufferfish` is open to contributions, however it should be noted that the library was created for my own game projects, and I am not interested in making it widely general-purpose. If you have a feature request or bug fix that you think would be useful to others, feel free to open an issue or PR either way.

typescript/README.md

@@ -2,42 +2,63 @@
 
 `bufferfish` is utility library for working with binary network messages between Rust and TypeScript, such as over WebSockets. It provides a simple API for encoding and decoding data into binary arrays, as well as generating TypeScript definitions and decoding functions from your Rust code.
 
-_This library has an unstable API and is missing a variety of functionality. I can't recommend using it in production, although I am using it for my own production project._
-
 See the [project repository](https://github.com/robertwayne/bufferfish) for more details, including how to interop with Rust.
 
+_This library has an unstable API and may be missing some basic functionality. I can't recommend using it in production, although I am using it for my own production project._
+
 ## Examples
 
+### Writing to a Bufferfish
+
 ```typescript
 import { Bufferfish } from 'bufferfish'
 
 const ws = new WebSocket("ws://127.0.0.1:3000")
 ws.binaryType = "arraybuffer"
 
 const bf = new Bufferfish()
+bf.writeUint8(0)
 bf.writeString("Hello, world!")
 
 ws.send(bf.view())
 ```
 
-### Manually Decoding Packets
+### Reading from a Bufferfish
+
+```typescript
+import { Bufferfish } from 'bufferfish'
+
+const ws = new WebSocket("ws://127.0.0.1:3000")
+ws.binaryType = "arraybuffer"
+
+onmessage = (event) => {
+  const bf = new Bufferfish(event.data)
+  const id = bf.readUint8()
+
+    if (id === 0) {
+        const message = bf.readString()
+
+        console.log({ message }) // { message: "Hello, world!" }
+    }
+}
+```
+
+## Using Generated Decoding Functions
+
+These are built when defining a struct or enum in Rust with the `#[derive(Encode)]` macro after calling the `bufferfish::generate()` function.
 
 ```typescript
 const ws = new WebSocket("ws://127.0.0.1:3000")
 ws.binaryType = "arraybuffer"
 
 ws.onmessage = (event) => {
-    const bf = new Bufferfish(event.data)
-    const packetId = bf.readUint16()
+  const bf = new Bufferfish(event.data)
+  const packetId = bf.readUint16()
 
     if (packetId === PacketId.Join) {
-        const id = bf.readUint32()
-        const username = bf.readString()
+        const packet = decodeJoinPacket(bf)
 
-        console.log({
-            id,
-            username,
-        }) // { id: 1, username: "Rob" }
+        console.log(packet) // { id: 1, username: "Rob" }
     }
 }
 ```
@@ -123,9 +144,11 @@ Supported Types             | Decodes As
 `Vec<T> where T: Encodable` | `Array<T>`
 `T where T: Encodable`      | `object` or primitive
 
+_*The reverse is true for decoding._
+
 ## Notes
 
-- I strongly recommend the usage of the [num_enum](https://github.com/illicitonion/num_enum) crate for deriving `IntoPrimitive` and `FromPrimitve` on your packet ID enum. This removes a lot of boilerplate.
+- I recommend using the [num_enum](https://github.com/illicitonion/num_enum) crate for deriving `IntoPrimitive` and `FromPrimitve` on enums you wish to `Encode`. This removes a lot of boilerplate.
 - Enums in TypeScript are often mentioned as a "bad" feature, and this is generally true when considering typical web development use-cases. In the case of a list of "op codes" mapping to dev-friendly names, however, they are actually really useful. Modern bundlers - like `esbuild` - [can actually inline them, meaning we just get integer literals in the final output.](https://sombia.com/posts/typescript-enums).
 
 ## Security
@@ -136,6 +159,10 @@ When reading data, you will always get the correct return type - however, you ar
 
 This kind of problem should be dealt with before operating on the buffer.
 
+Decoding an oversized bufferfish via the `Decode` trait will just ignore / discard the additional data, as it is only going to read specific byte lengths generated by the `Encodable` impl.
+
+Decoding an undersized bufferfish will return a `BufferfishError::FailedWrite`.
+
 ## Contributing
 
 `bufferfish` is open to contributions, however it should be noted that the library was created for my own game projects, and I am not interested in making it widely general-purpose. If you have a feature request or bug fix that you think would be useful to others, feel free to open an issue or PR either way.