From 6496a84f90c121a45341d2883bea08998f4c1284 Mon Sep 17 00:00:00 2001
From: Haaxor1689 <betkomaros@gmail.com>
Date: Sun, 26 Nov 2023 17:40:13 +0100
Subject: [PATCH] Added never type

---
 README.md    | 49 +++++++++++++++++++++++++++++++++++++++++++------
 package.json |  2 +-
 src/types.ts | 18 +++++++++++++++++-
 3 files changed, 61 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index df1f3c8..207246b 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ import { n } from '@haaxor1689/nil';
 
 // Declare object schema with given shape
 const User = n.object({
-	age: n.uint16(),
+	rank: n.uint16(),
 	active: n.int32()
 });
 
@@ -96,7 +96,7 @@ type User = n.output<typeof User>;
 
 // Equivalent to
 type User = {
-	age: number;
+	rank: number;
 	active: boolean;
 };
 ```
@@ -152,6 +152,8 @@ n.array(n.int16(), 'fill');
 The `.bytes()` option can be used to interpret a given length in bytes instead of the count of elements.
 
 ```ts
+import { n } from '@haaxor1689/nil';
+
 // Size will be 256 bytes
 n.buffer(256).bytes();
 n.string(256).bytes();
@@ -163,6 +165,8 @@ n.array(n.int8, 256).bytes();
 You can load **C** enum values as a string literal union. Only default numbered **C** enums are supported now.
 
 ```ts
+import { n } from '@haaxor1689/nil';
+
 // Declare enum schema with given options
 const Level = n.enum(n.int8(), ['LOW', 'MEDIUM', 'HIGH']);
 
@@ -188,12 +192,37 @@ enum Level {
 You can access the tuple used to create a given enum with `.options`.
 
 ```ts
+import { n } from '@haaxor1689/nil';
+
 // Declare enum schema with given options
 const Level = n.enum(n.int8(), ['LOW', 'MEDIUM', 'HIGH']);
 
 Level.options; // ["LOW", "MEDIUM", "HIGH"]
 ```
 
+## Never
+
+If you need a placeholder that represents 0 bytes in the binary data, you can use the never type for that:
+
+```ts
+import { n } from '@haaxor1689/nil';
+
+// Declare object schema with given shape
+const User = n.object({
+	empty: n.never(), // represents 0 bytes in buffer
+	active: n.int32()
+});
+
+// Extract the output type
+type User = n.output<typeof User>;
+
+// Equivalent to
+type User = {
+	empty: never;
+	active: boolean;
+};
+```
+
 ## Schema methods
 
 All Nil schemas contain these methods.
@@ -210,6 +239,8 @@ All Nil schemas contain these methods.
 You can provide custom transformation functions for your schemas that will change the output both when parsing from the raw buffer and creating a buffer from the JS object.
 
 ```ts
+import { n } from '@haaxor1689/nil';
+
 // Define transform that handles calculating `itemCount`
 const MySchema = n
 	.object({
@@ -217,8 +248,8 @@ const MySchema = n
 		items: n.array(n.int8(), ['itemCount'])
 	})
 	.transform(
-		v => v.items, // Keep only raw items
-		v => ({ itemCount: v.length, items: v }) // Calculate itemCount
+		v => v.items, // keep only raw items
+		v => ({ itemCount: v.length, items: v }) // calculate itemCount
 	);
 
 // Inferred output type is `number[]`
@@ -231,6 +262,8 @@ MySchema.toBuffer([1, 2, 3, 4]);
 You can also access the current context when creating transformations to reference other attributes from the parent type (if any). The easiest way to do this is by using the `resolvePath` helper function.
 
 ```ts
+import { n } from '@haaxor1689/nil';
+
 const MySchema = n.object({
 	hasAlpha: n.bool(),
 	data: n.array(n.int8(), 'fill').transform(
@@ -248,13 +281,17 @@ const MySchema = n.object({
 
 ### `.fromBuffer`
 
-`.fromBuffer(data: Uint8Array): Output`
+```ts
+.fromBuffer(data: Uint8Array): Output
+```
 
 Tries to parse given buffer into output type of used schema. Throws errors on failure.
 
 ### `.toBuffer`
 
-`.toBuffer(value: Output): Uint8Array`
+```ts
+.toBuffer(value: Output): Uint8Array
+```
 
 Tries to serialize a given object into a buffer.
 
diff --git a/package.json b/package.json
index b4331cf..d92e290 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@haaxor1689/nil",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "TypeScript-first binary data parsing library with static type inference",
 	"author": "Maroš Beťko <betkomaros@gmail.com>",
 	"repository": {
diff --git a/src/types.ts b/src/types.ts
index 9091d22..2b739be 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -597,6 +597,20 @@ export class NilEnum<
 	}
 }
 
+export class NilNever extends NilType<never> {
+	size() {
+		return 0;
+	}
+
+	_decode() {
+		return undefined as never;
+	}
+
+	_encode() {
+		// Do nothing
+	}
+}
+
 const bool = () => new NilBool({});
 const int8 = () => new NilNumber({ bytes: 1, signed: true });
 const uint8 = () => new NilNumber({ bytes: 1 });
@@ -622,6 +636,7 @@ const enum_ = <
 	type: T,
 	options: O
 ): NilEnum<T, O> => new NilEnum({ type, options });
+const never = () => new NilNever({});
 
 export {
 	bool,
@@ -639,5 +654,6 @@ export {
 	array,
 	object,
 	buffer,
-	enum_ as enum
+	enum_ as enum,
+	never
 };