Documentation: Datagram Serialization Module

This documentation provides an overview and explanation of datagram and serialization in skiff-crypto, which is responsible for serializing, deserializing, encrypting, and decrypting typed and versioned data objects.

Importing the Module

versioning.ts

import {
  Datagram,
  Envelope,
  AADMeta,
  TypedBytes,
  createJSONWrapperDatagram,
  createRawJSONDatagram,
  createRawCompressedJSONDatagram,
  createUint8ArrayDatagram
} from '@skiff-org/skiff-crypto';

Overview

The Datagram Serialization module provides functions and classes for handling datagrams, which are typed and versioned objects. Datagrams can be serialized, deserialized, encrypted, and decrypted, providing a structured way to work with data.

Interfaces

Typed

  • Description: An interface that defines an object with a type.
  • Properties:
    • type: string

Versioned

  • Description: An interface that defines an object with a version and version constraint.
  • Properties:
    • version: string
    • versionConstraint: Range

Serializable<T>

  • Description: An interface that defines an object that can be serialized into a Uint8Array.
  • Methods:
    • serialize(data: T): Uint8Array

Deserializable<T>

  • Description: An interface that defines an object that can be deserialized from a Uint8Array.
  • Methods:
    • deserialize(data: Uint8Array, version: string): T

Datagram<T>

  • Description: Combines Typed, Versioned, Serializable<T>, and Deserializable<T> interfaces to define the minimum set of functions needed to serialize and deserialize a typed and versioned object.

Classes

AADMeta

  • Description: A class that encapsulates additional metadata included in envelope implementations.
  • Constructor Parameters:
    • version: string
    • type: string
    • nonce: Uint8Array
  • Static Methods:
    • deserialize(data: Uint8Array): Deserializes the input data into metadata, raw metadata, and content.
  • Methods:
    • serialize(): Uint8Array: Serializes the AAD metadata.

TypedBytes

  • Description: An extension of Uint8Array with a function to inspect header metadata.
  • Methods:
    • inspect(): Inspects header metadata of the content.

Functions

createJSONWrapperDatagram<T>(type: string, version?: string, versionConstraint?: Range)

  • Description: Creates a datagram that encodes and decodes data in an object containing {version, type, data} in JSON format.
  • Parameters:
    • type: string - Datagram type.
    • version: string (optional) - Datagram version, default 0.1.0.
    • versionConstraint: Range (optional) - Version constraint, default 0.1.*.
  • Returns: Datagram<T>

createRawJSONDatagram<T>(type: string, version?: string, versionConstraint?: Range)

  • Description: Creates a datagram that encodes and decodes data in JSON format.
  • Parameters:
    • type: string - Datagram type.
    • version: string (optional) - Datagram version, default 0.1.0.
    • versionConstraint: Range (optional) - Version constraint, default 0.1.*.
  • Returns: Datagram<T>

createRawCompressedJSONDatagram<T>(type: string, version?: string, versionConstraint?: Range)

  • Description: Creates a datagram that encodes and decodes data in JSON format with gzip compression.
  • Parameters:
    • type: string - Datagram type.
    • version: string (optional) - Datagram version, default 0.1.0.
    • versionConstraint: Range (optional) - Version constraint, default 0.1.*.
  • Returns: Datagram<T>

createUint8ArrayDatagram(type: string, version?: string, versionConstraint?: Range)

  • Description: Creates a datagram that encodes and decodes a raw Uint8Array object, optimal for size optimization.
  • Parameters:
    • type: string - Datagram type.
    • version: string (optional) - Datagram version, default 0.1.0.
    • versionConstraint: Range (optional) - Version constraint, default 0.1.*.
  • Returns: Datagram<Uint8Array>

Example Usage

versioning.ts

import { createJSONWrapperDatagram, createUint8ArrayDatagram } from '@skiff-org/skiff-crypto';

// Create a JSON wrapper datagram
const jsonDatagram = createJSONWrapperDatagram<{ name: string }>('user-profile');

// Serialize data
const serializedData = jsonDatagram.serialize({ name: 'Alice' });

// Deserialize data
const deserializedData = jsonDatagram.deserialize(serializedData);

console.log(deserializedData); // { name: 'Alice' }

// Create a raw Uint8Array datagram
const uint8Datagram = createUint8ArrayDatagram('raw-data');

// Serialize data
const rawSerializedData = uint8Datagram.serialize(new Uint8Array([1, 2, 3]));

// Deserialize data
const rawDeserializedData = uint8Datagram.deserialize(rawSerializedData);

console.log(rawDeserializedData); // Uint8Array [ 1, 2, 3 ]

Note

Please ensure you understand the concepts and security implications before using serialization, especially when dealing with sensitive or encrypted data.