x/cav@0.0.21/client.ts

Weird Wide Web tools
GitHub Stars
2
Go to latest
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574
// Copyright 2022 Connor Logan. All rights reserved. MIT License.// This module is browser-compatible.
// TODO: The ability to monitor request progress (XMLHttpRequest)// TODO: The ability to specify custom headers
import { HttpError, serialize, serializeBody, deserialize, deserializeBody,} from "./serial.ts";
import type { Serializers } from "./serial.ts";import type { Parser, ParserFunction, ParserOutput,} from "./parser.ts";
/** * Cav's WebSocket wrapper interface. */export interface Socket<Send = unknown, Message = unknown> { /** * The raw WebSocket instance. */ raw: WebSocket; /** * Send data to the connected party. The data provided is serialized using the * top-level `serialize()` function. */ send: (data: Send) => void; /** * Closes the web socket connection. An optional code and reason may be * provided, and will be available to all "close" event listeners. */ close: (code?: number, reason?: string) => void; /** * Register an event listener for the "open" event, which is fired when the web * socket connection is established. The socket must be opened before any data * can be sent. */ on(type: "open", cb: SocketListener<"open">): void; /** * Register an event listener for the "close" event, which is fired when the * web socket connection is ended. */ on(type: "close", cb: SocketListener<"close">): void; /** * Register an event listener for the "message" event, which is fired every * time a message is received from the connected party. The message received * is deserialized and made available on the "message" property assigned to * the event. */ on(type: "message", cb: SocketListener<"message", Message>): void; /** * Register an event listener for the "error" event, which is fired when the * connection has been closed due to an error. */ on(type: "error", cb: SocketListener<"error">): void; /** * Unregister an event listener for a particular event type. If no listener is * provided, all listeners for that event type will be unregistered. If the * event type is also omitted, all listeners for the web socket will be * unregistered. */ off( type?: "open" | "close" | "message" | "error", cb?: (ev: Event) => void | Promise<void>, ): void;}
/** * Type that matches any socket. Useful for type constraints. */// deno-lint-ignore no-explicit-anyexport type AnySocket = Socket<any, any>;
/** * Type for a web socket event listener. The shape of the listener depends on * the event type. For the "message" event, the message type may be provided as * the second type parameter. */export type SocketListener< Type extends "open" | "close" | "message" | "error", Message = unknown,> = (ev: ( Type extends "open" ? Event : Type extends "close" ? CloseEvent : Type extends "message" ? MessageEvent & { message: Message } : Type extends "error" ? Event | ErrorEvent : never)) => void | Promise<void>;
/** * Initializer options to use when upgrading a request into a web socket using * the `upgradeWebSocket` function. */export interface SocketInit<Message extends Parser | null = null> { /** * Message parser, for parsing incoming messages. If this is ommitted, * messages won't be parsed and will be typed as "unknown". */ message?: Message; /** * Additional serializers to use when serializing and deserializing message * data. */ serializers?: Serializers | null;}
/** * Wraps a regular WebSocket with serializer functionality and type support. */export function wrapWebSocket< Send = unknown, Message extends Parser | null = null,>( raw: WebSocket, init?: SocketInit<Message>,): Socket<Send, Message extends Parser ? ParserOutput<Message> : unknown> { const listeners = { open: new Set<(ev: Event) => unknown>(), close: new Set<(ev: CloseEvent) => unknown>(), message: new Map<unknown, (ev: MessageEvent) => unknown>(), error: new Set<(ev: Event | ErrorEvent) => unknown>(), };
return { raw, send: data => { raw.send(JSON.stringify(serialize(data, init?.serializers))); }, close: (code, reason) => { raw.close(code, reason); }, on: (type, cb) => { const decoder = new TextDecoder();
// Only message gets a special process if (type !== "message") { listeners[type].add(cb as (ev: Event) => unknown); raw.addEventListener(type, cb as (ev: Event) => unknown); return; }
const messageListener = async (ev: MessageEvent) => { const data = ev.data; if ( typeof data !== "string" && !ArrayBuffer.isView(data) && !(data instanceof Blob) ) { throw new Error(`Invalid data received: ${data}`); } // deno-lint-ignore no-explicit-any let message: any = deserialize(JSON.parse( typeof data === "string" ? data : ArrayBuffer.isView(data) ? decoder.decode(data) : await data.text() // Blob ), init?.serializers); if (init?.message) { const parse: ParserFunction = ( typeof init.message === "function" ? init.message : init.message.parse ); message = await parse(message); }
Object.assign(ev, { message }); (cb as (ev: Event) => void)(ev); };
listeners.message.set(cb, messageListener); raw.addEventListener(type, messageListener); }, off: (type, cb) => { // If the callback isn't defined, turn off everything for the given type. // If the given type also isn't defined, turn off everything if (!cb) { const turnOff = (t: Exclude<typeof type, undefined>) => { for (const listener of listeners[t].values()) { raw.removeEventListener(t, listener as (ev: Event) => unknown); } listeners[t].clear(); }; if (!type) { for (const k of Object.keys(listeners)) { turnOff(k as keyof typeof listeners); } return; } turnOff(type); return; }
if (!type) { throw new Error("If a callback is specified, the event type must also be specified"); }
// Otherwise, only turn off the listener if it was registered with this // interface. Don't forget to remove it from the listeners, and that // message listeners are stored in a map instead of a set const listener = ( type === "message" ? listeners[type].get(cb) as (ev: Event) => unknown : listeners[type].has(cb) ? cb : undefined ); if (listener) { listeners[type].delete(cb); raw.removeEventListener(type, listener); } }, };}
/** * Generic handler type for server-defined Request handlers. */export type Handler = ( req: Request, // deno-lint-ignore no-explicit-any ...a: any[]) => Promise<Response> | Response;
// TODO: Add an Endpoint interface// TODO: Add a Router interface
/** * An endpoint handler can use this Request type to ferry type information to * the client from the server about what client arguments are acceptable. */export interface EndpointRequest< Query = never, Message = never, Upgrade = never,> extends Request { __cav?: { // imaginary endpointRequest: { query: Query; message: Message; upgrade: Upgrade; } routerRequest?: never; }}
/** * Response type used to ferry the type of the deserialized response to the * client from the server. If a server handler doesn't return this type, the * response type of the corresponding client call will be "unknown". */export interface EndpointResponse<T = unknown> extends Response { __cav?: { // imaginary endpointResponse: T; };}
/** * A router handler on the server can use this Request type to ferry type * information about valid routes to the client. The client uses the provided * RouterShape to infer which property accesses are valid. */export interface RouterRequest< Shape extends RouterShape = Record<never, never>,> extends Request { __cav?: { // imaginary endpointRequest?: never; routerRequest: Shape; };}
/** * Type constraint for the Shape parameter of a RouterRequest. The shape * describes the client property accesses that would result in a valid endpoint * call. */export interface RouterShape { [x: string]: ( | Handler | Handler[] | RouterShape | null );}
/** * A function that wraps `fetch()` with a tailored process for making requests * to a Cav server. Each property access on the function itself returns a new * Client that extends the URL of the original Client. The periods represent * path dividers and the accessed properties are path segments, like this: * `client("http://localhost/base").nested["pa.th"]()` will result in a request * to "http://localhost/base/nested/pa.th". * * The type parameter is the type of the handler this client points to, which * allows the client TypeScript to extract information about what data the * server expects to receive and respond with. */export type Client< T extends Handler | Handler[] | RouterShape | null = null,> = ( // Handler[] T extends Handler[] ? Client<T[number]> // Stack : T extends ( req: RouterRequest<infer S>, // deno-lint-ignore no-explicit-any ...a: any[] ) => Response | Promise<Response> ? Client<S> // Rpc : T extends ( req: EndpointRequest<infer Q, infer M, infer U>, // deno-lint-ignore no-explicit-any ...a: any[] ) => EndpointResponse<infer R> | Promise<EndpointResponse<infer R>> ? ( x: ClientArg<Q, M, U>, ) => Promise<R extends Socket<infer S, infer M2> ? Socket<M2, S> : R> // Handler /// deno-lint-ignore no-explicit-any // : T extends (req: Request, ...a: any[]) => Response | Promise<Response> ? ( // (x: ClientArg<unknown, unknown, unknown>) => Promise<unknown> // ) // When a router's type is specified, the router's shape is passed into the // client and gets handled here : T extends RouterShape ? UnionToIntersection<{ [K in keyof T]: ExpandPath<K, Client<T[K]>>; }[keyof T]> // Any other type results in an unknown response // deno-lint-ignore no-explicit-any : (x: ClientArg<any, any, any>) => Promise<unknown>);
/** * Arguments for the client function when its internal path points to an * endpoint. */export type ClientArg< Query = never, Message = never, Upgrade = never,> = Clean<{ /** * Additional path segments to use when making a request to this endpoint. * Including extra path segments should only be done if the endpoint expects * it. Default: `undefined` */ path?: string; /** * The query string parameters expected by the endpoint. Default: `undefined` */ query: Query; /** * If this isn't an upgraded endpoint, this is the posted message expected by * the Rpc. Default: `undefined` */ message: true extends Upgrade ? never : Message; /** * Additional serializers to use while serializing data. Default: `undefined` */ serializers?: Serializers; /** * If the endpoint requires upgrading for web sockets, this value should be * set to `true`. Default: `undefined` */ upgrade: true extends Upgrade ? true : never;}>;
interface CustomFetchArg { path?: string; query?: Record<string, string | string[]>; message?: unknown; serializers?: Serializers; upgrade?: boolean;}
/** * Constructs a new Client tied to a given base URL. The provided set of packers * will be used everywhere that data is packed/unpacked when using this client, * including web sockets. * * If the type parameter provided is a Stack or an Rpc, the returned client * function's type will be tailored to match the inputs and outputs expected on * the Stack/Rpc. In the case of Stacks, the returned client function is wrapped * in a Proxy that will translate property accesses into path segments to append * to the internal URL of the request. Once the client function is called (as * opposed to keyed into), the fetch process uses that internal URL. The generic * types are imaginary; they're used only to keep the server setup and the * client-side api accesses in sync with each other. When they get out of sync, * there will be a typescript error in the IDE but the bundleScript() process * will ignore the error. * * For example: * * ```ts * // On the server... (server.ts) * import { cav as c, zod as z } from "./deps.ts"; * * export type MyRpc = typeof myRpc; * * const myRpc = c.rpc({ * query: z.object({ * hi: z.string(), * }), * resolve: x => { * return `Hello, ${x.query.hi}!`; * }, * }); * * export type MyStack = typeof myStack; * * export const myStack = c.stack({ * // There's multiple ways to divide up stack routes. Here's two of those * // ways: * path: { * "to/rpc": myRpc, * }, * }); * * // On the client... (browser/app.tsx) * import type { MyStack, MyRpc } from "../server.ts"; // Discarded upon build * * // Each of these equates to the same request. The a/b/c variables below are * // all of type `Promise<string>`, which is automatically determined by the * // passed in type parameter. The final request will be: `GET * // /path/to/rpc?hi=world`. When the promises resolve, the strings will be * // "Hello, world!" * const a = client<MyStack>("/").path.to.rpc({ query: { hi: "world" } }); * const b = client<MyStack>("/")["path/to/rpc"]({ query: { hi: "world" } }); * const c = client<MyRpc>("/path/to/rpc")({ query: { hi: "world" } }); * ``` */export function client<T extends Handler | RouterShape | null = null>( base = "", serializers?: Serializers,): Client<T> { const customFetch = (path: string, x: CustomFetchArg = {}) => { // If there is an explicit origin in the path, it should override the second // argument. i.e. the second argument is just a fallback const url = new URL(path, self.location?.origin); if (x.query) { for (const [k, v] of Object.entries(x.query)) { if (Array.isArray(v)) { for (const v2 of v) { url.searchParams.append(k, v2); } } else { url.searchParams.append(k, v); } } } if (x.upgrade) { if (url.protocol === "http:") { url.protocol = "ws:"; } else { url.protocol = "wss:"; } const raw = new WebSocket(url.href, "json"); return wrapWebSocket(raw, { serializers: x.serializers }); } return (async () => { let body: BodyInit | null = null; let mime = ""; if (x.message) { const pb = serializeBody(x.message, x.serializers); body = pb.body; mime = pb.mime; } const method = body === null ? "GET" : "POST"; const res = await fetch(url.href, { method, headers: mime ? { "content-type": mime } : {}, body, }); let resBody: unknown = undefined; if (res.body) { resBody = await deserializeBody(res, x.serializers); } if (!res.ok) { const detail = { body: resBody }; let message: string; let status: number; let expose: unknown; if (resBody instanceof HttpError) { message = resBody.message; status = resBody.status; expose = resBody.expose; } else if (typeof resBody === "string") { message = resBody; status = res.status; expose = undefined; } else { message = res.statusText; status = res.status; expose = undefined; } throw new HttpError(message, { status, expose, detail }); } return resBody; })(); };
const proxy = (path: string, serializers?: Serializers): unknown => { return new Proxy((x: CustomFetchArg) => customFetch(path, { ...x, serializers: { ...serializers, ...x.serializers }, }), { get(_, property) { if (typeof property !== "string") { throw new TypeError("Symbol segments can't be used on the client"); } const append = property.split("/").filter(p => !!p).join("/"); return proxy( path.endsWith("/") ? path + append : path + "/" + append, serializers, ); } }); };
return proxy(base, serializers) as Client<T>;}
/** * Expands the route path from a Stack into an object representing the client * property accesses required to make a successful request for the given route. * Example: `ExpandPath<"hello/world", true>` becomes `{ hello: { world: true } * }` */type ExpandPath<K, T> = ( K extends `*` | `:${string}` ? { [x: string]: T } : K extends `:${string}/${infer P2}` ? { [x: string]: ExpandPath<P2, T> } : K extends `/${infer P}` | `${infer P}/` | `${infer P}/*` ? ExpandPath<P, T> : K extends `${infer P1}/${infer P2}` ? { [x in P1]: ExpandPath<P2, T> } : K extends string ? { [x in K]: T } : never);
type Clean< T, Required = { [K in keyof T as ( T[K] extends never ? never : undefined extends T[K] ? never : K )]: T[K]; }, Optional = { [K in keyof T as ( K extends keyof Required ? never : T[K] extends never ? never : K )]?: T[K]; },> = Required & Optional;
/** * https://fettblog.eu/typescript-union-to-intersection/ */type UnionToIntersection<U> = ( U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? { [K in keyof I]: I[K] } : never