@xyo-network/payload-model 3.6.0-rc.1 → 3.6.0-rc.11

package/src/Error.ts

@@ -13,7 +13,6 @@ export type ModuleError = Payload<{
   name?: string
   query?: Hash
   schema: ModuleErrorSchema
-  sources?: Hash[]
 }>
 
 export const isModuleError = isPayloadOfSchemaType<ModuleError>(ModuleErrorSchema)

package/src/Payload.ts

@@ -1,35 +1,55 @@
 import type { Hash } from '@xylabs/hex'
-import type { EmptyObject } from '@xylabs/object'
+import type {
+  DeepOmitStartsWith, DeepPickStartsWith, DeepRestrictToStringKeys, EmptyObject,
+} from '@xylabs/object'
 
 import type { Schema, WithSchema } from './Schema.ts'
 
-/** Additional fields for a payload */
-export interface PayloadFields extends EmptyObject {
-  schema: Schema
+export interface SchemaField<T extends Schema = Schema> {
+  schema: T
 }
 
-export type WithPayload<T extends EmptyObject | void = void> = WithSchema<T extends EmptyObject ? PayloadFields & T : PayloadFields>
+/** Additional fields for a payload */
+export interface PayloadFields extends SchemaField {}
+
+export type WithPayload<T extends EmptyObject | void = void> =
+  DeepRestrictToStringKeys<WithoutMeta<WithSchema<T extends EmptyObject ? PayloadFields & T : PayloadFields>>>
 
 /** Base Type for Payloads */
 export type Payload<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> =
   T extends WithSchema ?
     S extends Schema ?
       /* T (w/Schema) & S provided */
-      WithPayload<Omit<T, 'schema'> & { schema: S } & PayloadFields>
+      WithPayload<Omit<T, 'schema'> & { schema: S }>
       : /* Only T (w/Schema) provided */ WithPayload<T>
     : T extends object ?
       S extends Schema ?
       /* T (w/o Schema) & S provided */
-        WithPayload<T & { schema: S } & PayloadFields>
-        : /* Only T (w/o Schema) provided */ WithPayload<T & { schema: Schema } & PayloadFields>
+        WithPayload<T & { schema: S }>
+        : /* Only T (w/o Schema) provided */ WithPayload<T & PayloadFields>
       : /* Either just S or neither S or T provided */
-        {
-          schema: S extends Schema ? S : Schema
-        } & PayloadFields
+      WithPayload<{
+        schema: S extends Schema ? S : Schema
+      }>
+
+export type OverridablePayload<T extends Payload> = WithoutMeta<Omit<T, 'schema'> & PayloadFields>
 
-export type OverridablePayload<T extends Payload> = Omit<T, 'schema'> & { schema: string }
+export type SourcesMetaField = { $sources: Hash[] }
+
+export type WithSources<T extends EmptyObject> = T & SourcesMetaField
+export type WithOptionalSources<T extends EmptyObject> = (T & SourcesMetaField) | T
 
-export type WithSources<T extends EmptyObject> = T & { sources?: Hash[] }
 export type PayloadWithSources<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = WithSources<Payload<T, S>>
+export type PayloadWithOptionalSources<T extends void | EmptyObject | WithSchema = void, S extends Schema | void = void> = WithOptionalSources<Payload<T, S>>
+
+export type WithAnySchema<T extends Payload> = OverridablePayload<T>
+
+export type WithoutClientMeta<T extends EmptyObject> = DeepOmitStartsWith<T, '$'>
+export type WithoutStorageMeta<T extends EmptyObject> = DeepOmitStartsWith<T, '_'>
+export type WithoutPrivateStorageMeta<T extends EmptyObject> = DeepOmitStartsWith<T, '__'>
+export type WithoutMeta<T extends EmptyObject> = WithoutClientMeta<WithoutStorageMeta<T>>
+
+export type WithoutSchema<T extends WithOptionalSchema<Payload>> = Omit<T, 'schema'>
+export type WithOptionalSchema<T extends EmptyObject = EmptyObject> = WithoutSchema<T> & Partial<T & SchemaField>
 
-export type WithAnySchema<T extends Payload> = Omit<T, 'schema'> & { schema: string }
+export type WithOnlyClientMeta<T extends EmptyObject> = DeepPickStartsWith<T, '$'>

package/src/Query.ts

@@ -22,7 +22,7 @@ export type Query<T extends void | EmptyObject | WithSchema = void, S extends Sc
   T extends void ? QueryFields : T & QueryFields,
   S extends void ?
     T extends WithSchema ? T['schema']
-      : T extends void ? string
+      : T extends void ? Schema
         : void
     : S
 >

package/src/StorageMeta/Sequence.ts

@@ -0,0 +1,72 @@
+import type { Address, Hex } from '@xylabs/hex'
+import { isHex } from '@xylabs/hex'
+
+// we use Exclude to intentionally make the type not equal to string
+export type LocalSequence = Hex & Exclude<string, 'reserved-local-sequence-value'>
+export type QualifiedSequence = Hex & Exclude<string, 'reserved-qualified-sequence-value'>
+export type Sequence = LocalSequence | QualifiedSequence
+
+export type Epoch = Hex & Exclude<string, 'reserved-epoch-sequence-value'>
+
+export const isEpoch = (value: unknown): value is Epoch => {
+  return isHex(value) && (value as string).length === SequenceConstants.epochBytes * 2
+}
+
+export type Nonce = Hex & Exclude<string, 'reserved-nonce-sequence-value'>
+
+export const isNonce = (value: unknown): value is Epoch => {
+  return isHex(value) && (value as string).length === SequenceConstants.nonceBytes * 2
+}
+
+export const isLocalSequence = (value: unknown): value is Sequence => {
+  return isHex(value) && (value as string).length === SequenceConstants.localSequenceBytes * 2
+}
+
+export const isQualifiedSequence = (value: unknown): value is Sequence => {
+  return isHex(value) && (value as string).length === SequenceConstants.qualifiedSequenceBytes * 2
+}
+
+export const isSequence = (value: unknown): value is Sequence => {
+  return isLocalSequence(value) || isQualifiedSequence(value)
+}
+
+export const SequenceComponentLengths = {
+  epochBytes: 8,
+  nonceBytes: 8,
+  addressBytes: 20,
+}
+
+export const SequenceComponentMinMax = {
+  minEpoch: '0'.repeat(SequenceComponentLengths.epochBytes * 2) as Epoch,
+  maxEpoch: 'f'.repeat(SequenceComponentLengths.epochBytes * 2) as Epoch,
+  minNonce: '0'.repeat(SequenceComponentLengths.nonceBytes * 2) as Nonce,
+  maxNonce: 'f'.repeat(SequenceComponentLengths.nonceBytes * 2) as Nonce,
+  minAddress: '0'.repeat(SequenceComponentLengths.addressBytes * 2) as Address,
+  maxAddress: 'f'.repeat(SequenceComponentLengths.addressBytes * 2) as Address,
+}
+
+export const LocalSequenceConstants = {
+  ...SequenceComponentLengths,
+  ...SequenceComponentMinMax,
+  localSequenceBytes: SequenceComponentLengths.epochBytes + SequenceComponentLengths.nonceBytes,
+  minLocalSequence: SequenceComponentMinMax.minEpoch + SequenceComponentMinMax.minNonce as LocalSequence,
+  maxLocalSequence: SequenceComponentMinMax.maxEpoch + SequenceComponentMinMax.maxNonce as LocalSequence,
+}
+
+export const QualifiedSequenceConstants = {
+  qualifiedSequenceBytes: LocalSequenceConstants.localSequenceBytes + SequenceComponentLengths.addressBytes,
+  minQualifiedSequence: LocalSequenceConstants.minLocalSequence + SequenceComponentMinMax.minAddress as QualifiedSequence,
+  maxQualifiedSequence: LocalSequenceConstants.maxLocalSequence + SequenceComponentMinMax.maxAddress as QualifiedSequence,
+}
+
+export const SequenceConstants = {
+  ...LocalSequenceConstants,
+  ...QualifiedSequenceConstants,
+}
+
+// "11111111111111112222222222222222" is and example of a local sequence string
+
+// "111111111111111122222222222222223333333333333333333333333333333333333333" is and example of a local sequence string
+// epoch = "1111111111111111"
+// nonce = "2222222222222222"
+// address = "3333333333333333333333333333333333333333"

package/src/StorageMeta/SequenceParser.ts

@@ -0,0 +1,125 @@
+import { toUint8Array } from '@xylabs/arraybuffer'
+import { assertEx } from '@xylabs/assert'
+import {
+  type Address,
+  type Hash, type Hex,
+  isAddress,
+  toHex,
+} from '@xylabs/hex'
+
+import type {
+  Epoch, LocalSequence, Nonce, QualifiedSequence,
+  Sequence,
+} from './Sequence.ts'
+import {
+  isQualifiedSequence, isSequence, SequenceConstants,
+} from './Sequence.ts'
+
+export class SequenceParser {
+  protected static privateConstructorKey = Date.now().toString()
+
+  private readonly data: Readonly<Uint8Array>
+
+  protected constructor(privateConstructorKey: string, hex: Hex) {
+    assertEx(SequenceParser.privateConstructorKey === privateConstructorKey, () => 'Use create function instead of constructor')
+    const paddedHex = toHex(hex, {
+      prefix: false,
+      bitLength: (hex.length <= SequenceConstants.localSequenceBytes * 2)
+        ? SequenceConstants.localSequenceBytes * 8
+        : SequenceConstants.qualifiedSequenceBytes * 8,
+    })
+    this.data = toUint8Array(paddedHex)
+  }
+
+  get address(): Address {
+    const start = SequenceConstants.localSequenceBytes
+    const end = SequenceConstants.qualifiedSequenceBytes
+    return toHex(this.data.slice(start, end).buffer, { prefix: false })
+  }
+
+  get epoch(): Epoch {
+    const start = 0
+    const end = SequenceConstants.epochBytes
+    return toHex(this.data.slice(start, end).buffer, { prefix: false })
+  }
+
+  get localSequence(): LocalSequence {
+    const start = 0
+    const end = SequenceConstants.localSequenceBytes
+    return toHex(this.data.slice(start, end).buffer, { prefix: false })
+  }
+
+  get nonce(): Nonce {
+    const start = SequenceConstants.epochBytes
+    const end = SequenceConstants.localSequenceBytes
+    return toHex(this.data.slice(start, end).buffer, { prefix: false })
+  }
+
+  get qualifiedSequence(): QualifiedSequence {
+    const start = 0
+    const end = SequenceConstants.qualifiedSequenceBytes
+    return toHex(this.data.slice(start, end).buffer, { prefix: false })
+  }
+
+  static from(sequence: Sequence, address?: Address): SequenceParser
+  static from(timestamp: Hex, hash: Hash, address?: Address): SequenceParser
+  static from(timestamp: Hex, hash: Hex, address?: Address): SequenceParser
+  static from(timestamp: Hex, nonce: Nonce, address?: Address): SequenceParser
+  static from(timestamp: number, hash: Hash, address?: Address): SequenceParser
+  static from(timestamp: number, hash: Hex, address?: Address): SequenceParser
+  static from(timestamp: number, nonce: Nonce, address?: Address): SequenceParser
+  static from(timestampOrSequence: Sequence | Hex | number, nonceOrAddress: Hash | Nonce, address?: Address): SequenceParser {
+    if (isSequence(timestampOrSequence)) {
+      if (nonceOrAddress) {
+        assertEx(!isQualifiedSequence(timestampOrSequence), () => 'Providing both a qualified sequence and a address is not allowed')
+        assertEx(isAddress(nonceOrAddress), () => 'Invalid address provided')
+        return new this(SequenceParser.privateConstructorKey, (timestampOrSequence + address) as Hex)
+      }
+      return new this(SequenceParser.privateConstructorKey, timestampOrSequence)
+    }
+    const epoch = SequenceParser.toEpoch(timestampOrSequence)
+    const nonce = SequenceParser.toNonce(nonceOrAddress)
+    const addressHex: Hex = address ? toHex(address, { bitLength: SequenceConstants.addressBytes * 8 }) : SequenceConstants.minAddress
+    const hexString = (epoch + nonce + addressHex) as Hex
+    assertEx(isSequence(hexString), () => `Invalid sequence [${hexString}] [${epoch}, ${nonce}, ${addressHex}]`)
+    return new this(SequenceParser.privateConstructorKey, hexString)
+  }
+
+  static parse(value: Hex | string | ArrayBufferLike): SequenceParser {
+    const hex = toHex(value)
+    if (isSequence(hex)) {
+      return new this(SequenceParser.privateConstructorKey, hex)
+    }
+    throw new Error(`Invalid sequence [${value}]`)
+  }
+
+  // can convert a short number/hex to an epoch (treats it as the whole value) or extract an epoch from a sequence
+  static toEpoch(value: number | Hex | Epoch): Epoch {
+    assertEx(
+      typeof value !== 'number' || Number.isInteger(value),
+      () => 'Value must be in integer',
+    )
+    const hex = toHex(value, { prefix: false })
+    if (hex.length <= SequenceConstants.epochBytes * 2) {
+      return toHex(value, { prefix: false, bitLength: SequenceConstants.epochBytes * 8 }) as Epoch
+    }
+    if (isSequence(hex)) {
+      return hex.slice(0, SequenceConstants.epochBytes * 2) as Epoch
+    }
+    throw new Error(`Value could not be converted to epoch [${hex}]`)
+  }
+
+  // can convert a short number/hex to a nonce (treats it as the whole value) or extract an nonce from a sequence
+  static toNonce(value: Hash | Hex): Nonce {
+    assertEx(
+      typeof value !== 'number' || Number.isInteger(value),
+      () => 'Value must be in integer',
+    )
+    const hex = toHex(value, { prefix: false })
+    if (isSequence(hex)) {
+      return hex.slice(SequenceConstants.epochBytes * 2, SequenceConstants.localSequenceBytes * 2) as Nonce
+    }
+    const hash = toHex((hex as string), { prefix: false, bitLength: SequenceConstants.nonceBytes * 8 })
+    return hash.slice(-SequenceConstants.nonceBytes * 2) as Nonce
+  }
+}

package/src/StorageMeta/StorageMeta.ts

@@ -0,0 +1,46 @@
+import { type Hash, isHash } from '@xylabs/hex'
+
+import type { Payload } from '../Payload.ts'
+import type { Sequence } from './Sequence.ts'
+
+export interface SequenceMeta {
+  _sequence: Sequence
+}
+
+export type WithPartialSequenceMeta<T extends Payload = Payload> = Partial<WithSequenceMeta<T>>
+
+export type WithSequenceMeta<T extends Payload = Payload> = T & SequenceMeta
+
+export interface HashMeta {
+  _dataHash: Hash
+  _hash: Hash
+}
+
+export type WithPartialHashMeta<T extends Payload = Payload> = Partial<WithHashMeta<T>>
+
+export type WithHashMeta<T extends Payload = Payload> = T & HashMeta
+
+export interface StorageMeta extends SequenceMeta, HashMeta {}
+
+export type WithPartialStorageMeta<T extends Payload = Payload> = Partial<WithStorageMeta<T>>
+
+export type WithStorageMeta<T extends Payload = Payload> = T & StorageMeta
+
+export const isSequenceMeta = (value: unknown): value is SequenceMeta => {
+  return (value as WithSequenceMeta)?._sequence !== undefined
+}
+
+export const isHashMeta = (value: unknown): value is HashMeta => {
+  return isHash((value as WithHashMeta)?._hash) && isHash((value as WithHashMeta)?._dataHash)
+}
+
+export const isStorageMeta = (value: unknown): value is StorageMeta => {
+  return isSequenceMeta(value) && isHashMeta(value)
+}
+
+// "00005a7f354762f3ac1bc5ddc6cfd08d14" is and example of a local sequence string
+
+// "00005a7f354762f3ac1bc5ddc6cfd08d14a123456789abcdef0123" is and example of a local sequence string
+// epoch = "00005a7f354762f3ac"
+// nonce = "1bc5ddc6cfd08d14"
+// address = "a123456789abcdef0123"

package/src/StorageMeta/index.ts

@@ -0,0 +1,3 @@
+export * from './Sequence.ts'
+export * from './SequenceParser.ts'
+export * from './StorageMeta.ts'

package/src/index.ts

@@ -8,3 +8,4 @@ export * from './PayloadValidationFunction.ts'
 export * from './PayloadValueExpression.ts'
 export * from './Query.ts'
 export * from './Schema.ts'
+export * from './StorageMeta/index.ts'

package/src/isPayloadOfSchemaType.ts

@@ -7,7 +7,7 @@ export const isPayloadOfSchemaType = <T extends Payload>(schema: string) => {
 
 export const isPayloadOfSchemaTypeWithSources = <T extends Payload>(schema: string) => {
   return (x?: unknown | null): x is WithSources<T> =>
-    isPayloadOfSchemaType<WithSources<T>>(schema)(x) && x.sources !== undefined && Array.isArray(x.sources)
+    isPayloadOfSchemaType<WithSources<T>>(schema)(x) && x.$sources !== undefined && Array.isArray(x.$sources)
 }
 
 export const notPayloadOfSchemaType = <T extends Payload>(schema: string) => {