palbase 0.0.0-stage → 0.1.0

package/types/web/src/socket.d.ts

@@ -0,0 +1,87 @@
+export type Frame = [joinRef: string | null, ref: string | null, topic: string, event: string, payload: Record<string, unknown>];
+export interface SocketOptions {
+    /** https://<ref>.<domain> */
+    baseUrl: string;
+    publishableKey: string;
+    accessToken: () => Promise<string | undefined>;
+    /** The WebSocket constructor (globalThis.WebSocket by default). */
+    webSocket?: typeof WebSocket;
+    /** Pauses before each reconnection attempt, in ms; the last repeats. Jittered ±20%. */
+    backoff?: number[];
+    heartbeatMs?: number;
+    replyTimeoutMs?: number;
+}
+export type ChannelState = 'closed' | 'joining' | 'joined' | 'refused';
+/**
+ * What became of a push: the server's answer — `ok` with its response, or
+ * `error` with `{ reason }` — or, when none came, `timeout` (`no reply`: the
+ * server may have taken it) or `error` with `socket closed` or `not joined`.
+ */
+export interface PushReply {
+    status: string;
+    response: Record<string, unknown>;
+}
+type Listener = (payload: Record<string, unknown>) => void;
+export declare class Channel {
+    state: ChannelState;
+    /** Why the server refused the last join, when it did. */
+    refusal?: Record<string, unknown>;
+    joinRef: string | null;
+    private listeners;
+    private closers;
+    private joinWaiters;
+    readonly name: string;
+    private socket;
+    constructor(name: string, socket: RealtimeSocket);
+    get topic(): string;
+    /** Resolves once joined; rejects with the server's reason when refused. */
+    join(): Promise<void>;
+    leave(): void;
+    /**
+     * Sends one event on the joined channel and resolves with what became of it
+     * (PushReply) — never rejects for an answer, whatever it says. A channel
+     * that is not joined sends nothing. The server answers what it takes or
+     * refuses of a room's message and what it refuses of any other; a broadcast
+     * it took on a channel that is no room is answered by no one.
+     */
+    push(event: string, payload: Record<string, unknown>): Promise<PushReply>;
+    /** Listens to an event on this channel (a broadcast is the event "broadcast"); returns the unsubscribe. */
+    on(event: string, listener: Listener): () => void;
+    /**
+     * Listens for the end of what was joined here as the socket's user: the
+     * socket closed for good (the user signed out, or someone signed in) — not a
+     * drop, after which the channel is joined again. Returns the unsubscribe.
+     */
+    onClosed(listener: () => void): () => void;
+}
+export declare class RealtimeSocket {
+    private ws;
+    private opening;
+    private ref;
+    private channels;
+    private replies;
+    private heartbeat;
+    private heartbeatRef;
+    private reconnectTimer;
+    private attempts;
+    private closedByUs;
+    /** Counted for the app's own diagnostics: how many times the socket was opened again after a drop. */
+    reconnects: number;
+    private opts;
+    constructor(opts: SocketOptions);
+    channel(name: string): Channel;
+    /** Closes the socket; every channel is closed (the app joins again — as the next user, if one signs in). */
+    disconnect(): void;
+    /** A new token for every joined channel (the session was refreshed). */
+    tokenChanged(): Promise<void>;
+    private open;
+    private dropped;
+    private sendJoin;
+    private awaitReply;
+    private receive;
+    private push;
+    private nextRef;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+export {};

package/types/web/src/vite.d.ts

@@ -0,0 +1,49 @@
+export interface PalbaseViteOptions {
+    /** The app's slug (palbase apps:list): its file in palbase/. */
+    app: string;
+    /** Each mode the app is built in (vite --mode), and the environment it is built against. */
+    environments: Record<string, string>;
+    /** Where palbase apps:sync writes; palbase by default. */
+    dir?: string;
+    /** The app's tsconfig, from its root: tsconfig.app.json where there is one, else tsconfig.json. */
+    tsconfig?: string;
+    /** Type-check the app against its environment before a build (true). */
+    typecheck?: boolean;
+}
+interface Warning {
+    code?: string;
+    exporter?: string;
+    id?: string;
+    message: string;
+}
+type Warn = (w: Warning) => void;
+/** What a hook may ask of the bundler: to resolve an import as from another file. */
+interface ResolveContext {
+    resolve(source: string, importer: string, options: {
+        skipSelf: boolean;
+    }): Promise<unknown>;
+}
+/** What the plugin is to Vite: its hooks, typed here so the package needs no Vite of its own. */
+export interface PalbaseVitePlugin {
+    name: string;
+    enforce: 'pre';
+    config(user: {
+        build?: {
+            rollupOptions?: {
+                onwarn?: (w: Warning, warn: Warn) => void;
+            };
+        };
+    }, env: {
+        mode: string;
+        command?: string;
+    }): unknown;
+    configResolved(config: {
+        root: string;
+        mode: string;
+        command?: string;
+    }): void;
+    buildStart(): Promise<void>;
+    resolveId(this: ResolveContext, source: string, importer?: string): string | null | Promise<unknown>;
+}
+export declare function palbase(options: PalbaseViteOptions): PalbaseVitePlugin;
+export {};