Serialization¶

import { DurableContext, withDurableExecution } from "@aws/durable-execution-sdk-js";

interface Order {
  id: string;
  total: string;
}

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    // No SerDes config — the SDK serializes and deserializes the result automatically.
    const order = await context.step("fetch-order", async (): Promise<Order> => {
      return { id: "order-123", total: "99.99" };
    });
    return order;
  },
);

import { Serdes, SerdesContext } from "@aws/durable-execution-sdk-js";

// Serdes<T> interface
interface SerdesInterface<T> {
  serialize: (value: T | undefined, context: SerdesContext) => Promise<string | undefined>;
  deserialize: (data: string | undefined, context: SerdesContext) => Promise<T | undefined>;
}

// SerdesContext
interface SerdesContextShape {
  entityId: string;
  durableExecutionArn: string;
}

import { Serdes, SerdesContext } from "@aws/durable-execution-sdk-js";

interface Order {
  id: string;
  total: string;
}

const orderSerdes: Serdes<Order> = {
  serialize: async (value: Order | undefined, _ctx: SerdesContext) => {
    if (value === undefined) return undefined;
    return JSON.stringify(value);
  },
  deserialize: async (data: string | undefined, _ctx: SerdesContext) => {
    if (data === undefined) return undefined;
    return JSON.parse(data) as Order;
  },
};

import {
  DurableContext,
  Serdes,
  SerdesContext,
  StepConfig,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

interface Order {
  id: string;
  total: string;
}

const orderSerdes: Serdes<Order> = {
  serialize: async (value: Order | undefined, _ctx: SerdesContext) =>
    value !== undefined ? JSON.stringify(value) : undefined,
  deserialize: async (data: string | undefined, _ctx: SerdesContext) =>
    data !== undefined ? (JSON.parse(data) as Order) : undefined,
};

const stepConfig: StepConfig<Order> = { serdes: orderSerdes };

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    const order = await context.step(
      "fetch-order",
      async (): Promise<Order> => ({ id: "order-123", total: "99.99" }),
      stepConfig,
    );
    return order;
  },
);

import {
  DurableContext,
  Serdes,
  SerdesContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

interface ApprovalResult {
  approved: boolean;
  reason: string;
}

// Callbacks only need deserialization — the external system sends the payload.
const approvalSerdes: Omit<Serdes<ApprovalResult>, "serialize"> = {
  deserialize: async (data: string | undefined, _ctx: SerdesContext) =>
    data !== undefined ? (JSON.parse(data) as ApprovalResult) : undefined,
};

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    const [approval, callbackId] = await context.createCallback("await-approval", {
      serdes: approvalSerdes,
    });

    // Send callbackId to the external system here.
    console.log("Callback ID:", callbackId);

    const result = await approval;
    return result;
  },
);

import {
  BatchResult,
  DurableContext,
  MapConfig,
  Serdes,
  SerdesContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

interface ProcessedItem {
  id: string;
  status: string;
}

const itemSerdes: Serdes<ProcessedItem> = {
  serialize: async (value: ProcessedItem | undefined, _ctx: SerdesContext) =>
    value !== undefined ? JSON.stringify(value) : undefined,
  deserialize: async (data: string | undefined, _ctx: SerdesContext) =>
    data !== undefined ? (JSON.parse(data) as ProcessedItem) : undefined,
};

const mapConfig: MapConfig<string, ProcessedItem> = {
  itemSerdes,
};

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    const items = ["a", "b", "c"];
    const result: BatchResult<ProcessedItem> = await context.map(
      "process-items",
      items,
      async (_ctx, item) => ({ id: item, status: "done" }),
      mapConfig,
    );
    return result.getResults();
  },
);

import {
  DurableContext,
  createClassSerdes,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

class Order {
  id: string = "";
  total: string = "";

  label() {
    return `Order ${this.id} — ${this.total}`;
  }
}

const orderSerdes = createClassSerdes(Order);

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    const order = await context.step(
      "fetch-order",
      async () => Object.assign(new Order(), { id: "order-123", total: "99.99" }),
      { serdes: orderSerdes },
    );
    // order.label() works — class methods are preserved after deserialization
    return order.label();
  },
);

import {
  DurableContext,
  withDurableExecution,
  createFileSystemSerdes,
} from "@aws/durable-execution-sdk-js";

export const handler = withDurableExecution(
  async (event: { customerId: string }, context: DurableContext) => {
    const fsSerdes = createFileSystemSerdes("/mnt/s3");

    // Pass the FileSystem serdes to one step. Other operations in this handler
    // keep using the default JSON serdes.
    const profile = await context.step(
      "load-profile",
      async () => loadLargeProfile(event.customerId),
      { serdes: fsSerdes },
    );

    return { name: profile.name };
  },
);

declare function loadLargeProfile(
  customerId: string,
): Promise<{ name: string }>;

import {
  Serdes,
  FileSystemSerdesConfig,
} from "@aws/durable-execution-sdk-js";

export type CreateFileSystemSerdes = (
  basePath: string,
  config?: FileSystemSerdesConfig,
) => Serdes<unknown>;

import {
  FileSystemSerdesMode,
  FileSystemPathEncoding,
} from "@aws/durable-execution-sdk-js";

export interface FileSystemSerdesConfig {
  storageMode?: FileSystemSerdesMode;
  pathEncoding?: FileSystemPathEncoding;
  generatePreview?: (value: unknown) => Record<string, unknown> | undefined;
}

import {
  createFileSystemSerdes,
  FileSystemSerdesMode,
} from "@aws/durable-execution-sdk-js";

// Small payloads stay inline in the checkpoint. The SDK only writes to the
// filesystem when the checkpoint envelope would exceed the size limit.
export const overflowFileSystemSerdes = createFileSystemSerdes("/mnt/s3", {
  storageMode: FileSystemSerdesMode.OVERFLOW,
});

import {
  createFileSystemSerdes,
  FileSystemPathEncoding,
} from "@aws/durable-execution-sdk-js";

// Hash the ARN and the entity ID into fixed-length, filesystem-safe segments.
// Use HASH when entity IDs may contain unsafe characters or be very long.
export const hashedFileSystemSerdes = createFileSystemSerdes("/mnt/s3", {
  pathEncoding: FileSystemPathEncoding.HASH,
});

import {
  createFileSystemSerdes,
  buildPreview,
  PreviewMode,
} from "@aws/durable-execution-sdk-js";

// The checkpoint envelope stores the file pointer plus a small preview object,
// so the console can show id and status without reading the full file. The
// email field is visible but masked, so PII does not land in the checkpoint.
export const previewFileSystemSerdes = createFileSystemSerdes("/mnt/s3", {
  generatePreview: (value) =>
    buildPreview(value, {
      mode: PreviewMode.EXCLUDE_ALL,
      include: [{ name: "id" }, { name: "status" }],
      mask: [{ name: "email" }],
    }),
});

import {
  DurableContext,
  withDurableExecution,
  createFileSystemSerdes,
} from "@aws/durable-execution-sdk-js";

export const handler = withDurableExecution(
  async (event: { customerId: string }, context: DurableContext) => {
    // Configure once. Every step result, child-context result, invoke result,
    // and waitForCondition result in this handler is now stored on /mnt/s3.
    context.configureSerdes({
      defaultSerdes: createFileSystemSerdes("/mnt/s3"),
    });

    const profile = await context.step("load-profile", async () => {
      return loadLargeProfile(event.customerId);
    });

    return { name: profile.name };
  },
);

declare function loadLargeProfile(
  customerId: string,
): Promise<{ name: string }>;