npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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/types

The 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 JSON

Accept 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; // string

Pattern: 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 string

Pattern: 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 JSONPrimitive

Pattern: 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); // number

Versioning

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

Author

Sergio Xalambrí