API reference

Functions

defineEntity

Source

defineEntity<const TName extends string, const TFields extends EntityFieldMap, TIdSchema extends AnyCanonicalSchema = z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, TRelationshipIdSchema extends AnyCanonicalSchema = z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>(options: DefineEntityOptions<TName, TFields, TIdSchema, TRelationshipIdSchema>) => EntityDefinition<TName, BindRelationshipSchemas<TFields, TRelationshipIdSchema>, TIdSchema>

Exported from: @nexload-sdk/payload-schema

Public function exported by @nexload-sdk/payload-schema.

isPayloadSchemaError

Source

isPayloadSchemaError(error: unknown) => error is PayloadSchemaError<PayloadSchemaErrorCode>
isPayloadSchemaError<TCode extends PayloadSchemaErrorCode>(error: unknown, code: TCode) => error is PayloadSchemaError<TCode>

Exported from: @nexload-sdk/payload-schema

Public function exported by @nexload-sdk/payload-schema.

Classes

PayloadSchemaError

Source

class PayloadSchemaError

Exported from: @nexload-sdk/payload-schema

Public classe exported by @nexload-sdk/payload-schema.

Constants

defaultIdSchema

Source

defaultIdSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>

Exported from: @nexload-sdk/payload-schema

Public constant exported by @nexload-sdk/payload-schema.

field

Source

field: Readonly<{ text: <TNullable extends boolean = false>(options?: TextFieldOptions<TNullable>) => FieldDefinition<"text", NullableSchema<string, TNullable>, TextField>; textarea: <TNullable extends boolean = false>(options?: TextareaFieldOptions<TNullable>) => FieldDefinition<"textarea", NullableSchema<string, TNullable>, TextareaField>; slug: <TNullable extends boolean = false>(options?: TextFieldOptions<TNullable>) => FieldDefinition<"slug", NullableSchema<string, TNullable>, TextField>; number: <TNullable extends boolean = false>(options?: NumberFieldOptions<TNullable>) => FieldDefinition<"number", NullableSchema<number, TNullable>, NumberField>; money: <TNullable extends boolean = false>(options: MoneyFieldOptions<TNullable>) => FieldDefinition<"money", NullableSchema<number, TNullable>, NumberField>; boolean: <TNullable extends boolean = false>(options?: BooleanFieldOptions<TNullable>) => FieldDefinition<"boolean", NullableSchema<boolean, TNullable>, CheckboxField>; date: <TNullable extends boolean = false>(options?: DateFieldOptions<TNullable>) => FieldDefinition<"date", NullableSchema<string, TNullable>, DateField>; select: <const TValues extends readonly string[], THasMany extends boolean = false, TNullable extends boolean = false>(options: SelectFieldOptions<TValues, THasMany, TNullable>) => FieldDefinition<"select", NullableSchema<THasMany extends true ? TValues[number][] : TValues[number], TNullable>, SelectField>; relationship: <const TRelationTo extends string | readonly string[], THasMany extends boolean = false, TNullable extends boolean = false, TIdSchema extends AnyCanonicalSchema | undefined = undefined>(options: RelationshipFieldOptions<TRelationTo, THasMany, TNullable, TIdSchema>) => RelationshipFieldDefinition<"relationship", TRelationTo, THasMany, TNullable, TIdSchema, RelationshipField>; upload: <const TRelationTo extends string | readonly string[], THasMany extends boolean = false, TNullable extends boolean = false, TIdSchema extends AnyCanonicalSchema | undefined = undefined>(options: UploadFieldOptions<TRelationTo, THasMany, TNullable, TIdSchema>) => RelationshipFieldDefinition<"upload", TRelationTo, THasMany, TNullable, TIdSchema, UploadField>; group: <const TFields extends EntityFieldMap, TNullable extends boolean = false>(options: GroupFieldOptions<TFields, TNullable>) => FieldDefinition<"group", GroupCanonicalSchema<TFields, TNullable>, NamedGroupField>; array: <const TFields extends EntityFieldMap, TNullable extends boolean = false>(options: ArrayFieldOptions<TFields, TNullable>) => FieldDefinition<"array", ArrayCanonicalSchema<TFields, TNullable>, ArrayField>; richText: <TSchema extends AnyCanonicalSchema, TNullable extends boolean = false>(options: RichTextFieldOptions<TSchema, TNullable>) => FieldDefinition<"richText", TNullable extends true ? z.ZodNullable<TSchema> : TSchema, RichTextField>; native: <TPayloadField extends PayloadDataField, TSchema extends AnyCanonicalSchema | undefined = undefined>(options: NativeFieldOptions<TPayloadField, TSchema>) => FieldDefinition<"native", TSchema, TPayloadField>; }>

Exported from: @nexload-sdk/payload-schema

Public constant exported by @nexload-sdk/payload-schema.

Interfaces

ArrayFieldOptions

Source

interface ArrayFieldOptions<TFields extends EntityFieldMap, TNullable extends boolean = false> {
  fields: TFields
  required?: boolean
  nullable?: TNullable
  minRows?: number
  maxRows?: number
  defaultValue?: unknown
  dynamicDefaultValue?: DynamicDefaultValue<unknown>
  payload?: NativePayloadExtras<ArrayField, "fields" | "maxRows" | "minRows">
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

DefineEntityOptions

Source

interface DefineEntityOptions<
  TName extends string,
  TFields extends EntityFieldMap,
  TIdSchema extends AnyCanonicalSchema,
  TRelationshipIdSchema extends AnyCanonicalSchema
> {
  name: TName
  fields: TFields
  idSchema?: TIdSchema
  relationshipIdSchema?: TRelationshipIdSchema
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

EntityDefinition

Source

interface EntityDefinition<
  TName extends string,
  TFields extends EntityFieldMap,
  TIdSchema extends AnyCanonicalSchema
> {
  readonly name: TName
  readonly idSchema: TIdSchema
  readonly fields: TFields
  readonly payload: EntityPayloadFacade<TFields>
  schema<TSchema extends AnyCanonicalSchema>(factory: (context: EntitySchemaContext<TFields>) => TSchema): TSchema
  inspect(): EntityInspection
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

EntityInspection

Source

interface EntityInspection { name: string, fields: EntityInspectionFieldMap }

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

EntitySchemaContext

Source

interface EntitySchemaContext<TFields extends EntityFieldMap> {
  readonly fields: CanonicalSchemaMap<TFields>
  readonly pick: EntitySchemaPicker<TFields>
  readonly z: typeof import("zod").z
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

EntitySchemaPicker

Source

interface EntitySchemaPicker<TFields extends EntityFieldMap> {
  <
    const TKeys extends readonly (keyof CanonicalSchemaMap<TFields>)[],
    const TOptional extends readonly SelectedKey<TKeys>[] | "all" | undefined = undefined,
    const TRequired extends readonly SelectedKey<TKeys>[] | undefined = undefined
  >(
    keys: TKeys,
    options?: SchemaPickOptions<SelectedKey<TKeys>, TOptional, TRequired>,
  ): ZodObjectForPickedFields<TFields, TKeys, TOptional, TRequired>
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

FieldDefinition

Source

interface FieldDefinition<
  TKind extends string,
  TSchema extends AnyCanonicalSchema | undefined,
  TPayloadField extends PayloadDataField
> {
  readonly kind: TKind
  readonly schema: TSchema
  readonly __payloadFieldType?: TPayloadField
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

GroupFieldOptions

Source

interface GroupFieldOptions<TFields extends EntityFieldMap, TNullable extends boolean = false> {
  fields: TFields
  required?: boolean
  nullable?: TNullable
  defaultValue?: unknown
  dynamicDefaultValue?: DynamicDefaultValue<unknown>
  payload?: NativePayloadExtras<NamedGroupField, "fields">
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

NativeFieldOptions

Source

interface NativeFieldOptions<
  TPayloadField extends PayloadDataField,
  TSchema extends AnyCanonicalSchema | undefined = undefined
> {
  payload: Omit<TPayloadField, "defaultValue" | "name">
  schema?: TSchema
  defaultValue?: TSchema extends AnyCanonicalSchema ? z.input<TSchema> : never
  dynamicDefaultValue?: Extract<DefaultValue, (...args: never[]) => unknown>
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

PayloadSchemaErrorDataMap

Source

interface PayloadSchemaErrorDataMap {
  INVALID_ENTITY_NAME: { received: string }
  INVALID_FIELD_NAME: { entity?: string, field: string }
  RESERVED_FIELD_NAME: { entity?: string, field: string, reservedName: string }
  INVALID_FIELD_CONFIGURATION: { entity?: string, fieldPath: string, fieldKind: string, reason: string }
  INVALID_CONSTRAINT_RANGE: {
    entity?: string
    fieldPath: string
    constraint: string
    minimum?: number | string
    maximum?: number | string
  }
  INVALID_DEFAULT_VALUE: { entity?: string, fieldPath: string, fieldKind: string, issues: SafeIssueSummary[] }
  CONFLICTING_DEFAULT_CONFIGURATION: {
    entity?: string
    fieldPath: string
    fieldType: string
    configuredDefaults: readonly ["defaultValue", "dynamicDefaultValue"]
  }
  EMPTY_SELECT_VALUES: { entity?: string, fieldPath: string }
  INVALID_RELATIONSHIP_CONFIGURATION: {
    entity?: string
    fieldPath: string
    reason: string
    relationTo?: string[]
  }
  INVALID_NESTED_FIELD_CONFIGURATION: {
    entity?: string
    fieldPath: string
    reason: string
    blockingFieldPath?: string
  }
  ASYNC_CANONICAL_SCHEMA_UNSUPPORTED: { entity?: string, fieldPath: string, fieldKind: string }
  RESERVED_PAYLOAD_OPTION: { entity?: string, fieldPath: string, fieldKind: string, option: string }
  DUPLICATE_PAYLOAD_FIELD_NAME: { entity: string, payloadName: string, fieldPaths: string[] }
  INVALID_PAYLOAD_FIELD: { entity: string, fieldPath: string, fieldKind: string, reason: string }
  PAYLOAD_COMPILATION_FAILED: {
    entity: string
    fieldPath?: string
    fieldKind?: string
    operation: "all" | "field" | "pick"
    causeName?: string
  }
  UNKNOWN_FIELD: { entity: string, field: string, availableFields: string[] }
  SCHEMA_UNAVAILABLE: {
    entity: string
    fieldPath: string
    fieldKind: string
    reason: "native-without-schema" | "schema-less-descendant"
    blockingFieldPath?: string
  }
  INVALID_SCHEMA_FACTORY_RESULT: { entity: string, receivedType: string }
  SCHEMA_DERIVATION_FAILED: { entity: string, causeName?: string }
  INTERNAL_INVARIANT_VIOLATION: { invariant: string, entity?: string, fieldPath?: string }
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

RelationshipFieldOptions

Source

interface RelationshipFieldOptions<
  TRelationTo extends string | readonly string[],
  THasMany extends boolean = false,
  TNullable extends boolean = false,
  TIdSchema extends AnyCanonicalSchema | undefined = undefined
> {
  relationTo: TRelationTo
  hasMany?: THasMany
  required?: boolean
  nullable?: TNullable
  idSchema?: TIdSchema
  defaultValue?: MaybeNullable<
    RelationshipValueForOptions<TRelationTo, THasMany, TIdSchema>,
    TNullable
  >
  dynamicDefaultValue?: DynamicDefaultValue<unknown>
  payload?: NativePayloadExtras<RelationshipField, "hasMany" | "relationTo">
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

RichTextFieldOptions

Source

interface RichTextFieldOptions<
  TSchema extends AnyCanonicalSchema,
  TNullable extends boolean = false
> {
  schema: TSchema
  required?: boolean
  nullable?: TNullable
  defaultValue?: MaybeNullable<z.input<TSchema>, TNullable>
  dynamicDefaultValue?: DynamicDefaultValue<MaybeNullable<z.input<TSchema>, TNullable>>
  payload?: NativePayloadExtras<RichTextField>
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

SelectFieldOptions

Source

interface SelectFieldOptions<
  TValues extends readonly string[],
  THasMany extends boolean = false,
  TNullable extends boolean = false
> {
  values: TValues
  labels?: Partial<Record<TValues[number], string>>
  hasMany?: THasMany
  required?: boolean
  nullable?: TNullable
  defaultValue?: MaybeNullable<THasMany extends true ? TValues[number][] : TValues[number], TNullable>
  dynamicDefaultValue?: DynamicDefaultValue<
    MaybeNullable<THasMany extends true ? TValues[number][] : TValues[number], TNullable>
  >
  payload?: NativePayloadExtras<SelectField, "hasMany" | "options">
}

Exported from: @nexload-sdk/payload-schema

Public interface exported by @nexload-sdk/payload-schema.

Types

BooleanFieldOptions

Source

type BooleanFieldOptions<TNullable extends boolean = false> = CommonFieldOptions<
  boolean,
  TNullable,
  NativePayloadExtras<CheckboxField>
>;

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

DateFieldOptions

Source

type DateFieldOptions<TNullable extends boolean = false> = CommonFieldOptions<
  string,
  TNullable,
  NativePayloadExtras<DateField>
> & { minimum?: string, maximum?: string };

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

DefaultIdSchema

Source

type DefaultIdSchema = typeof defaultIdSchema;

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

EntityFieldMap

Source

type EntityFieldMap = Readonly<Record<string, AnyFieldDefinition>>;

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

InferEntityField

Source

type InferEntityField<TField extends FieldDefinition<string, AnyCanonicalSchema, PayloadDataField>>
  = z.infer<TField["schema"]>;

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

InferEntityFields

Source

type InferEntityFields<TEntity extends EntityDefinition<string, EntityFieldMap, AnyCanonicalSchema>> = {
  [TKey in keyof TEntity["fields"]]: TEntity["fields"][TKey]["schema"] extends AnyCanonicalSchema
    ? z.infer<TEntity["fields"][TKey]["schema"]>
    : never
};

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

MoneyFieldOptions

Source

type MoneyFieldOptions<TNullable extends boolean = false> = Omit<
  NumberFieldOptions<TNullable>,
  "integer" | "safe"
> & { currency: string };

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

NumberFieldOptions

Source

type NumberFieldOptions<TNullable extends boolean = false> = CommonFieldOptions<
  number,
  TNullable,
  NativePayloadExtras<NumberField, "max" | "min">
> & {
  integer?: boolean
  safe?: boolean
  minimum?: number
  maximum?: number
  multipleOf?: number
};

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

PayloadSchemaErrorCode

Source

type PayloadSchemaErrorCode = keyof PayloadSchemaErrorDataMap;

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

PayloadSchemaErrorPhase

Source

type PayloadSchemaErrorPhase = "definition" | "internal" | "payload-compilation" | "schema-derivation";

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

SerializedPayloadSchemaError

Source

type SerializedPayloadSchemaError<TCode extends PayloadSchemaErrorCode = PayloadSchemaErrorCode> = {
  name: "PayloadSchemaError"
  code: TCode
  phase: PayloadSchemaErrorPhase
  message: string
  data: PayloadSchemaErrorDataMap[TCode]
};

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

TextFieldOptions

Source

type TextFieldOptions<TNullable extends boolean = false> = CommonFieldOptions<
  string,
  TNullable,
  NativePayloadExtras<TextField, "maxLength" | "minLength">
> & {
  trim?: boolean
  lowercase?: boolean
  uppercase?: boolean
  minLength?: number
  maxLength?: number
  pattern?: RegExp
};

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

TextareaFieldOptions

Source

type TextareaFieldOptions<TNullable extends boolean = false> = CommonFieldOptions<
  string,
  TNullable,
  NativePayloadExtras<TextareaField, "maxLength" | "minLength">
> & Omit<TextFieldOptions<TNullable>, keyof CommonFieldOptions<string, TNullable, unknown> | "payload">;

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

UploadFieldOptions

Source

type UploadFieldOptions<
  TRelationTo extends string | readonly string[],
  THasMany extends boolean = false,
  TNullable extends boolean = false,
  TIdSchema extends AnyCanonicalSchema | undefined = undefined
> = Omit<RelationshipFieldOptions<TRelationTo, THasMany, TNullable, TIdSchema>, "payload"> & { payload?: NativePayloadExtras<UploadField, "hasMany" | "relationTo"> };

Exported from: @nexload-sdk/payload-schema

Public type exported by @nexload-sdk/payload-schema.

Runtime exports

• defineEntity(options) validates and binds a named field map, then returns the entity facade.
• field is a frozen namespace of 14 field factories.
• defaultIdSchema accepts a non-empty string or safe integer.
• PayloadSchemaError represents package definition, compilation, derivation, and invariant failures.
• isPayloadSchemaError(error, code?) narrows any package error or one exact code.

Entity facade

entity.payload.all(), .field(key), and .pick(keys) return ordinary Payload fields. entity.schema(factory) supplies { fields, pick, z } and accepts any Zod schema result. entity.inspect() returns deterministic safe metadata without raw configs, schemas, functions, or values.

Types

The root exports field option types, entity/context/picker types, inference helpers, and the structured error map. PayloadSchemaErrorCode is exactly keyof PayloadSchemaErrorDataMap. InferEntityField and InferEntityFields infer canonical schema outputs, not Payload documents.

Error phases

PayloadSchemaErrorPhase is definition | payload-compilation | schema-derivation | internal. Ordinary invalid field data is a Payload ValidationError, not a PayloadSchemaError.

See the root entrypoint and public types.