wirejs-resources

Experimental: WireJS is an experimental hobby project and is not production software. For a professionally supported project in a similar spirit, see AWS Blocks, which benefits from lessons and ideas explored here.

Experimental deployment-neutral resources, request context, and service abstractions for WireJS applications.

This package can be used by WireJS apps, API modules, SSR/SSG code, deployment adapters, or other Node code that wants cloud/host/provider-agnostic resource abstractions. App code describes what it needs; local and deployment-specific packages decide how those resources are implemented.

What is in this package?

• Resource — the base identity/scope model used by all resources.
• Context, CookieJar, SignedCookie — request/runtime context and cookie helpers.
• Data/config resources — Setting, KeyValueStore, DistributedTable.
• Invocation resources — Endpoint, BackgroundJob, CronJob.
• Runtime metadata — SystemAttribute.
• Services — FileService, AuthenticationService, OIDC provider presets, RealtimeService, LLM, EmailSender.
• Override hooks — deployment packages can swap local implementations for cloud/provider implementations.

Detailed docs

• Core concepts: resources, scopes, overrides, and context
• Data/config resources: Setting, KeyValueStore, DistributedTable
• Invocation resources: Endpoint, BackgroundJob, CronJob, SystemAttribute
• Services: FileService, AuthenticationService, RealtimeService, LLM, EmailSender

Quick example

import {
	Context,
	DistributedTable,
	Endpoint,
	PassThruParser,
	Setting,
} from 'wirejs-resources';

const siteTitle = new Setting('site', 'title', {
	private: false,
	description: 'Human-readable site title',
	init: () => 'My WireJS app',
});

type Todo = {
	userId: string;
	id: string;
	status: 'open' | 'done';
	title: string;
};

const todos = new DistributedTable('app', 'todos', {
	parse: PassThruParser<Todo>,
	key: {
		partition: { field: 'userId', type: 'string' },
		sort: { field: 'id', type: 'string' },
	},
	indexes: [
		{ partition: { field: 'status', type: 'string' } },
	],
});

new Endpoint('api', 'open-todos', {
	path: '/open-todos',
	description: 'List open todos for a user.',
	handle: async (context: Context) => {
		const userId = context.location.searchParams.get('userId') ?? 'anonymous';
		const title = await siteTitle.read();
		const items = [];

		for await (const todo of todos.query({
			by: 'userId-id',
			where: { userId },
			filter: { status: { eq: 'open' } },
		})) {
			items.push(todo);
		}

		context.responseHeaders['content-type'] = 'application/json; charset=utf-8';
		return JSON.stringify({ title, items });
	},
});

Exports

Common exports include:

import {
	Context,
	CookieJar,
	SignedCookie,
	Resource,
	Setting,
	DistributedTable,
	PassThruParser,
	KeyValueStore,
	Endpoint,
	BackgroundJob,
	CronJob,
	SystemAttribute,
	FileService,
	AuthenticationService,
	GoogleOIDCProvider,
	GitHubOIDCProvider,
	RealtimeService,
	LLM,
	EmailSender,
	overrides,
	withContext,
	requiresContext,
} from 'wirejs-resources';

WireJS is experimental. Expect breaking changes and check the README/docs installed with your exact package version after upgrading.