Memory Value Validation Helper

What it does#

isMemoryJsonValue is a TypeScript type-guard function that checks whether an arbitrary JavaScript value conforms to the MemoryJsonValue type Primitive Memories accepts. Call it before writing a value with client.memories.set to fail fast on invalid input instead of getting a rejected API request.

It is defined in the workspace-internal api-core package and reaches consumers through @primitivedotdev/sdk/api:

import { isMemoryJsonValue } from "@primitivedotdev/sdk/api";

isMemoryJsonValue({ step: 2, done: false }); // true
isMemoryJsonValue(undefined); // false

Signature#

function isMemoryJsonValue(value: unknown): value is MemoryJsonValue;

Returns: boolean. When true, TypeScript narrows value to MemoryJsonValue in the calling scope.

The MemoryJsonValue type#

type MemoryJsonValue =
  | null
  | string
  | number
  | boolean
  | MemoryJsonValue[]
  | { [key: string]: MemoryJsonValue };

This is the exact type the generated OpenAPI client uses for the Memories API's value field. It is recursive: array elements and object property values must themselves be valid MemoryJsonValues.

What is accepted#

What is rejected#

Where it's used internally#

The Node SDK's client.memories.set calls the same validation logic on its value field before sending the request, so a value that fails isMemoryJsonValue also fails at client.memories.set with a TypeError:

client.memories.set value must be a JSON value: string, finite number, boolean,
null, array, or plain object. Undefined, bigint, symbol, function, NaN, Infinity,
sparse arrays, class instances, and cyclic values are not valid memory values.

Calling isMemoryJsonValue yourself lets you validate a value earlier in your code path, for example, before constructing the object you plan to store, or when accepting arbitrary data from an upstream source.

Example: guarding a value before storing it#

import {
  createPrimitiveClient,
  isMemoryJsonValue,
} from "@primitivedotdev/sdk/api";

const client = createPrimitiveClient({ apiKey: process.env.PRIMITIVE_API_KEY! });


function toStorableState(candidate: unknown): Record<string, unknown> {
  if (!isMemoryJsonValue(candidate)) {
    throw new TypeError("state is not a valid Primitive Memories JSON value");
  }
  return candidate as Record<string, unknown>;
}

const state = toStorableState({ step: 2, lastEmailId: "em_123" });

await client.memories.set({ key: "thread:latest", value: state });

Related fix in codegen#

The generated MemoryJsonValue TypeScript type required a post-processing repair step during codegen, because @hey-api/openapi-ts widens the recursive type: "null" branch of the schema to unknown. See Generated TypeScript Client Fixups for how fix-generated-api-imports.ts patches this.

Next steps#