tessl/npm-xyo-network--payload-model

Core payload modeling capabilities for the XYO Protocol 2.0 ecosystem, offering TypeScript interfaces and types for defining, validating, and manipulating payloads within the XYO blockchain network.

Overview

Eval results

Files

XYO Network Payload Model

Name: tessl/npm-xyo-network--payload-model
Author: tessl

XYO Network Payload Model provides core payload modeling capabilities for the XYO Protocol 2.0 ecosystem. It offers comprehensive TypeScript interfaces and types for defining, validating, and manipulating payloads within the XYO blockchain network, including essential abstractions for payload schemas, validation functions, value expressions, and query mechanisms.

Package Information

Package Name: @xyo-network/payload-model
Package Type: npm
Language: TypeScript
Installation: npm install @xyo-network/payload-model

Core Imports

Core Types and Interfaces:

import { 
  // Base payload types
  Payload, 
  PayloadFields,
  PayloadMetaFields,
  Schema,
  
  // Type guards and validation
  isPayload, 
  isPayloadOfSchemaType,
  isAnyPayload,
  isSchema,
  
  // Storage metadata
  StorageMeta,
  WithStorageMeta,
  SequenceParser
} from "@xyo-network/payload-model";

Advanced Types and Utilities:

import {
  // Validation functions
  PayloadValidationFunction,
  SyncPayloadValidationFunction,
  AsyncPayloadValidationFunction,
  
  // Bundles and queries
  PayloadBundle,
  PayloadBundleFields,
  Query,
  QueryFields,
  
  // Error handling
  ModuleError,
  
  // Utility types
  PayloadFindFilter,
  PayloadHashMap,
  PayloadValueExpression,
  PayloadProperty,
  PayloadValue,
  
  // PayloadSet types
  PayloadSet,
  PayloadSetPayload,
  
  // Timestamp utilities
  Timestamp,
  WithTimestamp,
  
  // Zod schemas
  PayloadZod,
  StorageMetaZod,
  AnyPayloadZod
} from "@xyo-network/payload-model";

Sequence and Storage Types:

import {
  // Sequence types
  Sequence,
  LocalSequence,
  QualifiedSequence,
  Epoch,
  Nonce,
  
  // Storage metadata interfaces
  HashStorageMeta,
  DataHashStorageMeta,
  SequenceStorageMeta,
  
  // Constants
  SequenceConstants,
  LocalSequenceConstants,
  QualifiedSequenceConstants
} from "@xyo-network/payload-model";

For CommonJS:

const { 
  // Core types
  Payload, 
  Schema, 
  isPayload, 
  isPayloadOfSchemaType,
  
  // Storage metadata
  StorageMeta,
  SequenceParser,
  
  // Validation
  PayloadValidationFunction,
  
  // Utilities
  PayloadBundle,
  Query,
  ModuleError
} = require("@xyo-network/payload-model");

Basic Usage

import { 
  Payload, 
  isPayload, 
  isPayloadOfSchemaType,
  Schema 
} from "@xyo-network/payload-model";

// Define a custom payload type
const MySchema = "network.example.my-payload" as const;
interface MyPayload extends Payload {
  data: string;
  timestamp: number;
  schema: typeof MySchema;
}

// Create a payload
const payload: MyPayload = {
  schema: MySchema,
  data: "hello world",
  timestamp: Date.now()
};

// Validate payload structure
if (isPayload([MySchema])(payload)) {
  console.log("Valid payload");
}

// Type-safe schema validation
const isMyPayload = isPayloadOfSchemaType<MyPayload>(MySchema);
if (isMyPayload(payload)) {
  // TypeScript knows this is MyPayload
  console.log(payload.data);
}

Architecture

The XYO Network Payload Model is built around several key components:

Core Payload System: Base Payload<T, S> type with flexible generic typing for custom payload structures
Schema System: String-based schema identification with regex validation and branded types
Type Guards: Comprehensive validation functions for runtime type checking and narrowing
Storage Metadata: Hash-based and sequence-based metadata tracking for blockchain storage
Query System: Structured query interface for payload discovery and filtering
Bundle System: Grouping multiple related payloads with root hash references
Validation Framework: Sync/async validation functions with Zod integration
Value Expression System: Type-safe property extraction and manipulation utilities

Capabilities

Core Payload Types

Foundation types and interfaces for XYO Protocol payloads, including the base Payload<T, S> type, schema definitions, and metadata handling.

type Payload<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = 
  (T extends WithSchema
    ? S extends Schema
      ? WithPayload<Omit<T, 'schema'> & { schema: S }>
      : WithPayload<T>
    : T extends object
      ? S extends Schema
        ? WithPayload<T & { schema: S }>
        : WithPayload<T & PayloadFields>
      : WithPayload<{
        schema: S extends Schema ? S : Schema
      }>) & Partial<PayloadMetaFields>;

type Schema = string;

interface PayloadFields extends SchemaField {
  schema: Schema;
}

Core Payload Types

Type Guards and Validation

Runtime validation functions for payload structure verification and type narrowing, including schema-specific type guards and validation utilities.

function isPayload<T extends Payload>(schema: string[]): (value: unknown) => value is T;

function isPayloadOfSchemaType<T extends Payload | never = never>(
  schema: T['schema']
): (x?: unknown | null) => x is T;

function isAnyPayload(value: unknown): value is Payload;

Type Guards and Validation

Storage Metadata

Hash-based and sequence-based metadata system for tracking payloads in blockchain storage, including data hash, storage hash, and sequence management.

interface StorageMeta extends SequenceStorageMeta, HashStorageMeta {
  _hash: Hash;
  _dataHash: Hash;
  _sequence: Sequence;
}

type WithStorageMeta<T extends Payload = Payload> = T & StorageMeta;

class SequenceParser {
  static from(sequence: Sequence, address?: Address): SequenceParser;
  get address(): Address;
  get epoch(): Epoch;
  get localSequence(): LocalSequence;
  get nonce(): Nonce;
  get qualifiedSequence(): QualifiedSequence;
}

Storage Metadata

Payload Bundles and Queries

System for grouping related payloads and structured querying capabilities for payload discovery and filtering.

interface PayloadBundleFields<T extends Payload = Payload> {
  payloads: T[];
  root: Hash;
}

type PayloadBundle = Payload<PayloadBundleFields, PayloadBundleSchema>;

interface QueryFields {
  address?: Address | Address[];
  budget?: number;
  maxFrequency?: 'once' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
  minBid?: number;
}

type Query<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = 
  Payload<T extends void ? QueryFields : T & QueryFields, S>;

Payload Bundles and Queries

Validation and Error Handling

Comprehensive validation framework with sync/async validation functions, error payload structures, and Zod integration for runtime validation.

type PayloadValidationFunction<T extends Payload = Payload> = 
  SyncPayloadValidationFunction<T> | AsyncPayloadValidationFunction<T>;

type SyncPayloadValidationFunction<T extends Payload = Payload> = (payload: T) => boolean;

type AsyncPayloadValidationFunction<T extends Payload = Payload> = (payload: T) => Promise<boolean>;

interface ModuleError extends Payload {
  details?: JsonValue;
  message?: string;
  name?: string;
  query?: Hash | Schema;
  schema: ModuleErrorSchema;
}

Validation and Error Handling

Utility Types

Additional utility types for payload manipulation, filtering, value expressions, and type transformations.

interface PayloadFindFilter {
  limit?: number;
  order?: 'desc' | 'asc';
  schema?: string | string[];
}

interface PayloadHashMap<TPayload extends Payload = Payload, TId extends string | number | symbol = Hash> {
  dataHash: Record<TId, TId>;
  hash: Record<TId, TPayload>;
}

type PayloadValueExpression<T extends Payload = Payload, Key extends PayloadProperty<T> = PayloadProperty<T>, TValue = PayloadValue<T, Key>> = 
  (payload: T) => TValue;

Utility Types

Install with Tessl CLI

npx tessl i tessl/npm-xyo-network--payload-model

docs

bundles-queries.md

core-payload-types.md

tessl/npm-xyo-network--payload-model

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

XYO Network Payload Model

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Core Payload Types

Type Guards and Validation

Storage Metadata

Payload Bundles and Queries

Validation and Error Handling

Utility Types

index.mddocs/