TLS-20 Add serializer functions to JS/TS library

README.md

@@ -17,12 +17,63 @@ npm install @timeleap/sia
 ```python
 import { Sia } from "@timeleap/sia";
 
+type Person = {
+  name?: string;
+  age?: number;
+};
+
+const sia = new Sia();
+const person: Person = { name: "Pouya", age: 33 };
+
+const payload = sia
+  .seek(0)
+  .addAscii(person.name ?? "")
+  .addUInt8(person.age ?? 0)
+  .toUint8ArrayReference();
+
+console.log(payload); // Uint8Array(7) [5, 80, 111, 117, 121, 97,  33]
+
+const desia = new Sia(payload);
+const deserialized: Person = {
+  name: desia.readAscii(),
+  age: desia.readUInt8(),
+};
+
+console.log(deserialized); // { name: 'Pouya', age: 33 }
+```
+
+## Serializers
+
+Sia provides a set of serializers for each primitive type. They are most useful for cases where you're adding an array of values. Instead of writing the function yourself, just use the exported utility functions.
+
+```typescript
+import { Sia, serializeString8ArrayItem } from "@timeleap/sia";
+
 const sia = new Sia();
 
-sia
-  .addString8("Hello")
-  .addUint8(25)
-  .addAscii("World");
+sia.addArray8(["Hello", "World"], serializeString8ArrayItem);
+```
+
+The `serializeString8ArrayItem` runs for each item in the array and adds the item to the Sia content.
+
+## Deserializers
+
+For the opposite scenario, where you want to read an array of values from the Sia content, you can use the `readArray8` method in combination with the deserializers.
+
+```typescript
+import {
+  Sia,
+  serializeString8ArrayItem,
+  readString8ArrayItem,
+} from "@timeleap/sia";
+
+const sia = new Sia();
+
+sia.addArray8(["Hello", "World"], serializeString8ArrayItem);
+
+const desia = new Sia().setContent(sia.content);
+
+const deserialized = desia.readArray8(readString8ArrayItem);
 
-console.log(sia.content);
+console.log(deserialized); // ["Hello", "World"]
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timeleap/sia",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",

src/index.ts

@@ -1,6 +1,6 @@
-import { Buffer } from "./buffer.js";
 import { pack, unpack } from "utfz-lib";
 import { asciiToUint8Array, uint8ArrayToAscii } from "./ascii.js";
+import { Buffer } from "./buffer.js";
 
 const GLOBAL_SHARED_UNSAFE_BUFFER = new Uint8Array(32 * 1024 * 1024);
 
@@ -403,3 +403,5 @@ export class Sia extends Buffer {
     return this.readArray(length, fn);
   }
 }
+
+export * from "./serializers.js";

src/serializers.ts

@@ -0,0 +1,147 @@
+import { Sia } from "./index.js";
+
+// Serializers
+export function serializeInt8ArrayItem(sia: Sia, value: number) {
+  return sia.addInt8(value);
+}
+
+export function serializeInt16ArrayItem(sia: Sia, value: number) {
+  return sia.addInt16(value);
+}
+
+export function serializeInt32ArrayItem(sia: Sia, value: number) {
+  return sia.addInt32(value);
+}
+
+export function serializeInt64ArrayItem(sia: Sia, value: number) {
+  return sia.addInt64(value);
+}
+
+export function serializeUInt8ArrayItem(sia: Sia, value: number) {
+  return sia.addUInt8(value);
+}
+
+export function serializeUInt16ArrayItem(sia: Sia, value: number) {
+  return sia.addUInt16(value);
+}
+
+export function serializeUInt32ArrayItem(sia: Sia, value: number) {
+  return sia.addUInt32(value);
+}
+
+export function serializeUInt64ArrayItem(sia: Sia, value: number) {
+  return sia.addUInt64(value);
+}
+
+export function serializeString8ArrayItem(sia: Sia, value: string) {
+  return sia.addString8(value);
+}
+
+export function serializeString16ArrayItem(sia: Sia, value: string) {
+  return sia.addString16(value);
+}
+
+export function serializeString32ArrayItem(sia: Sia, value: string) {
+  return sia.addString32(value);
+}
+
+export function serializeString64ArrayItem(sia: Sia, value: string) {
+  return sia.addString64(value);
+}
+
+export function serializeByteArray8ArrayItem(sia: Sia, value: Uint8Array) {
+  return sia.addByteArray8(value);
+}
+
+export function serializeByteArray16ArrayItem(sia: Sia, value: Uint8Array) {
+  return sia.addByteArray16(value);
+}
+
+export function serializeByteArray32ArrayItem(sia: Sia, value: Uint8Array) {
+  return sia.addByteArray32(value);
+}
+
+export function serializeByteArray64ArrayItem(sia: Sia, value: Uint8Array) {
+  return sia.addByteArray64(value);
+}
+
+export function serializeBoolArrayItem(sia: Sia, value: boolean) {
+  return sia.addBool(value);
+}
+
+export function serializeBigIntArrayItem(sia: Sia, value: bigint) {
+  return sia.addBigInt(value);
+}
+
+// Deserializers
+export function deserializeInt8ArrayItem(sia: Sia) {
+  return sia.readInt8();
+}
+
+export function deserializeInt16ArrayItem(sia: Sia) {
+  return sia.readInt16();
+}
+
+export function deserializeInt32ArrayItem(sia: Sia) {
+  return sia.readInt32();
+}
+
+export function deserializeInt64ArrayItem(sia: Sia) {
+  return sia.readInt64();
+}
+
+export function deserializeUInt8ArrayItem(sia: Sia) {
+  return sia.readUInt8();
+}
+
+export function deserializeUInt16ArrayItem(sia: Sia) {
+  return sia.readUInt16();
+}
+
+export function deserializeUInt32ArrayItem(sia: Sia) {
+  return sia.readUInt32();
+}
+
+export function deserializeUInt64ArrayItem(sia: Sia) {
+  return sia.readUInt64();
+}
+
+export function deserializeString8ArrayItem(sia: Sia) {
+  return sia.readString8();
+}
+
+export function deserializeString16ArrayItem(sia: Sia) {
+  return sia.readString16();
+}
+
+export function deserializeString32ArrayItem(sia: Sia) {
+  return sia.readString32();
+}
+
+export function deserializeString64ArrayItem(sia: Sia) {
+  return sia.readString64();
+}
+
+export function deserializeByteArray8ArrayItem(sia: Sia) {
+  return sia.readByteArray8();
+}
+
+export function deserializeByteArray16ArrayItem(sia: Sia) {
+  return sia.readByteArray16();
+}
+
+export function deserializeByteArray32ArrayItem(sia: Sia) {
+  return sia.readByteArray32();
+}
+
+export function deserializeByteArray64ArrayItem(sia: Sia) {
+  return sia.readByteArray64();
+}
+
+export function deserializeBoolArrayItem(sia: Sia) {
+  return sia.readBool();
+}
+
+export function deserializeBigIntArrayItem(sia: Sia) {
+  return sia.readBigInt();
+}