@sdxc/types
v2026.10.13
Published
Shared TypeScript types
Readme
@sdxc/types
Shared TypeScript types for async return values, JSON boundaries and type-level checks.
Installation
npm add @sdxc/typesThe package ships types only, so import everything with import type.
Usage
Name what an async function resolves to
import type { ResolvedType } from "@sdxc/types";
async function fetchUser(id: string): Promise<{ name: string; email: string }> {
return { name: id, email: `${id}@example.com` };
}
type User = ResolvedType<typeof fetchUser>; // { name: string; email: string }Accept only values that survive JSON
Use JSONValue as a generic bound: the caller keeps their own shape, and anything JSON cannot
carry is rejected at the call site.
import type { JSONValue } from "@sdxc/types";
function enqueue<T extends JSONValue>(payload: T): T {
return payload;
}
let job = enqueue({ id: 1, tags: ["news"], draft: false });
job.tags; // string[]
enqueue({ when: new Date() }); // Error: a Date comes back as a string
enqueue({ run: () => 1 }); // Error: functions are not JSONAccept anything JSON.stringify can write
JSONSerializable adds objects with a toJSON, such as Date and URL.
import type { JSONSerializable } from "@sdxc/types";
function write<T extends JSONSerializable>(payload: T): string {
return JSON.stringify(payload);
}
write({ publishedAt: new Date(), href: new URL("https://example.com") });Type what comes back
JSONSerialized<T> is the shape a written value has after JSON.parse.
import type { JSONSerialized } from "@sdxc/types";
type Stored = JSONSerialized<{ id: number; publishedAt: Date; edit: () => void }>;
// { id: number; publishedAt: string }API
ResolvedType<T extends (...args: any) => Promise<any>>
The value an async function resolves to; shorthand for Awaited<ReturnType<T>>.
JSONPrimitive
string | number | boolean | null. Take it where a value is compared, indexed or used as a key,
so the signature says a structure has no meaning there.
JSONValue
JSONPrimitive | JSONValue[] | { [key: string]: JSONValue }: a value that comes back from
JSON.parse identical to what was written. Use it as a generic bound (T extends JSONValue); as
a plain parameter type it widens the argument and the caller loses their shape.
JSONSerializable
JSONValue plus { toJSON(): JSONSerializable } at any depth: every value JSON.stringify
accepts. Take it where a value is written and JSONValue (or JSONSerialized<T>) where it is
read back, since the reader receives the toJSON replacement.
JSONSerialized<T>
What T becomes after a JSON round trip: toJSON is applied, unwritable properties are dropped,
and unwritable array elements become null. A JSONValue comes back unchanged.
JSONSerialized<Date>; // string
JSONSerialized<undefined[]>; // null[]
JSONSerialized<[string, Date]>; // [string, string]It describes the shape, so it tracks nine levels of nesting and widens to JSONValue below
that, and it keeps getters and inherited properties that JSON.stringify leaves out.
IsAny<T>
true when T is any, false for every other type, unknown included. Equivalent to
0 extends 1 & T ? true : false.
Pattern: Typing a consumer from its data function
Name the data once, at its source, and derive props and item types from it with indexed access.
import type { ResolvedType } from "@sdxc/types";
async function listPosts() {
return { posts: [{ id: "1", title: "Hello" }], total: 1 };
}
type PostList = ResolvedType<typeof listPosts>;
type Post = PostList["posts"][number]; // { id: string; title: string }
interface PostRowProps {
post: Post;
}
let pending = listPosts(); // hand the promise on unawaited
pending.then((list: PostList) => list.posts.map((post): PostRowProps => ({ post })));Pattern: A typed queue across a JSON boundary
The producer may send a Date; the consumer is typed with the string it will actually receive.
import type { JSONSerializable, JSONSerialized } from "@sdxc/types";
class Topic<T extends JSONSerializable> {
#messages: string[] = [];
push(message: T): void {
this.#messages.push(JSON.stringify(message));
}
pull(): JSONSerialized<T> | undefined {
let raw = this.#messages.shift();
return raw === undefined ? undefined : JSON.parse(raw);
}
}
let posts = new Topic<{ id: number; publishedAt: Date }>();
posts.push({ id: 1, publishedAt: new Date() });
let message = posts.pull();
message?.publishedAt; // stringPattern: A cache that only stores round-trippable values
When the value read back must be the value written, constrain the write to JSONValue.
import type { JSONValue } from "@sdxc/types";
class Cache {
#entries = new Map<string, string>();
set<T extends JSONValue>(key: string, value: T): void {
this.#entries.set(key, JSON.stringify(value));
}
get<T extends JSONValue>(key: string): T | undefined {
let raw = this.#entries.get(key);
return raw === undefined ? undefined : JSON.parse(raw);
}
}
let cache = new Cache();
cache.set("plans", ["free", "pro"]);
cache.set("now", new Date()); // Error: read back, it would be a stringPattern: Filters over scalar fields
JSONPrimitive keeps comparisons to values that compare meaningfully.
import type { JSONPrimitive } from "@sdxc/types";
interface Condition {
field: string;
value: JSONPrimitive;
}
function eq(field: string, value: JSONPrimitive): Condition {
return { field, value };
}
eq("plan", "pro");
eq("seats", null);
eq("plan", { tier: "pro" }); // Error: an object is not a JSONPrimitivePattern: Turning any into unknown
IsAny lets a helper refuse to pass any through, so a caller narrows the result of
JSON.parse before using it.
import type { IsAny } from "@sdxc/types";
type Known<T> = IsAny<T> extends true ? unknown : T;
function read<T>(load: () => T): Known<T> {
return load() as Known<T>;
}
let parsed = read(() => JSON.parse('{"id":1}')); // unknown
let count = read(() => 42); // numberVersioning
Releases are dated rather than semantic. A version is the UTC date it was published, written YYYY.M.D, so 2026.9.4 is the release from 4 September 2026. At most one release goes out per day.
Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
Depend on one exact date, and move it when you are ready to take the change:
{
"dependencies": {
"@sdxc/types": "2026.9.4"
}
}A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
License
MIT
