@trypattern/sdk 0.0.0-stage → 0.1.1

package/dist/app.d.ts

@@ -0,0 +1,115 @@
+import type { DataRouter } from 'react-router';
+import type { AppApi } from './api.ts';
+import { AppStore } from './appInfo.ts';
+import { SessionStore } from './auth/sessionStore.ts';
+import type { Cache } from './cache.ts';
+import type { Clock } from './clock.ts';
+import type { Gate } from './gate.ts';
+import { ActionsStore } from './actions.ts';
+import type { Action, ActionsBuilder } from './actions.ts';
+import { Toasts } from './builtins/Toasts.ts';
+import { PageStore } from './page.ts';
+import type { BuiltInModels } from './registered.ts';
+import type { Snapshots } from './store.ts';
+import type { Json, Persisted } from './state.ts';
+import type { DerivedOf, Instances, MessagesOf, ModelClassLike, ModelSnapshots } from './model.ts';
+import type { PageOf, PathOf, RouteDefinition } from './routes.ts';
+import type { Services } from './services.ts';
+import type { Tables } from './table.ts';
+import { PublicTableStore, TableStore } from './tables.ts';
+type Observed = {
+    readonly state: object;
+    readonly subscribe: (listener: () => void) => () => void;
+};
+export type { DataRouter };
+export type ModelServicesOf<Path extends string> = {
+    navigate: (to: Path) => Promise<void>;
+    every: (ms: number, run: () => void | Promise<void>) => () => void;
+};
+type StaticTypeError<Text extends string> = Text;
+type NonJsonGetters<Instance> = {
+    [Key in keyof DerivedOf<Instance>]: DerivedOf<Instance>[Key] extends Json | undefined ? never : Key;
+}[keyof DerivedOf<Instance>];
+export type PlainJsonModel<Class> = Class extends abstract new (...args: never[]) => infer Instance ? [NonJsonGetters<Instance>] extends [never] ? Class : StaticTypeError<`Getter ${NonJsonGetters<Instance> & string} must return plain JSON (strings, numbers, booleans, null, and arrays and objects of those, or undefined), because flows compare the snapshot`> : Class;
+export type NavigateCommand<Path extends string> = {
+    type: 'app.navigate';
+    to: Path;
+};
+export type PressKeyCommand = {
+    type: 'app.pressKey';
+    key: string;
+};
+export type AppDependencies<Api> = {
+    api: Api;
+    cache: Cache;
+    gate: Gate;
+    clock?: Clock;
+};
+export type RunningApp<Command, Snapshot extends {
+    readonly path: string;
+}> = {
+    readonly router: DataRouter;
+    send(command: Command): Promise<void>;
+    parse(raw: unknown): Command | {
+        error: string;
+    };
+    getSnapshot(): Snapshot;
+    whenIdle(): Promise<void>;
+    tick(): void;
+};
+export type StoreClasses = Record<string, new (persisted: Persisted, services: never) => Observed>;
+export type StoreInstances<Classes extends StoreClasses> = {
+    [Key in keyof Classes]: InstanceType<Classes[Key]>;
+};
+export type TableStores<Group extends Tables> = {
+    [Key in keyof Group as Group[Key]['access']['read'] extends 'server' ? never : Key]: TableStore<Group[Key]>;
+};
+export type PublicStores<Group extends Tables> = {
+    [Key in keyof Group & string as [Group[Key]['public'][number]] extends [
+        never
+    ] ? never : `public${Capitalize<Key>}`]: PublicTableStore<Group[Key]>;
+};
+export type StoresOf<Group extends Tables, Custom, Item extends Action = Action> = {
+    session: SessionStore;
+    app: AppStore;
+    actions: ActionsStore<Item>;
+    toasts: Toasts;
+    page: PageStore;
+} & TableStores<Group> & PublicStores<Group> & Custom;
+export type AppDefinition<Group extends Tables, Custom extends StoreClasses, Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[]> = {
+    tables: Group;
+    stores?: Custom;
+    models: {
+        [Key in keyof Classes]: Key extends keyof BuiltInModels | 'app' ? StaticTypeError<`${Key & string} is a built-in model of @trypattern/sdk: its state, answers and commands come from Pattern. Name yours for what it holds.`> : PlainJsonModel<Classes[Key]>;
+    };
+    routes: Routes;
+    actions?: readonly ActionsBuilder<never, Action>[];
+    actionGroups?: readonly string[];
+    services?: Services;
+    memory?: object;
+};
+export type AppClass<Group extends Tables, Instance> = {
+    new (router: DataRouter, deps: AppDependencies<AppApi<Group>>): Instance;
+    readonly definition: {
+        readonly tables: Group;
+        readonly routes: readonly RouteDefinition[];
+        readonly services?: Services;
+        readonly memory?: object;
+    };
+};
+export type AppSnapshotShape<Models, Stores, Page> = {
+    page: Page | null;
+    path: string;
+    models: ModelSnapshots<Models>;
+    stores: Snapshots<Stores>;
+};
+type AppCommandOf<Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[]> = MessagesOf<Instances<BuiltInModels>> | MessagesOf<Instances<Classes>> | NavigateCommand<PathOf<Routes>> | PressKeyCommand;
+export type DefinedApp<Group extends Tables, Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[], Custom extends StoreClasses> = {
+    new (router: DataRouter, dependencies: AppDependencies<AppApi<Group>>): RunningApp<AppCommandOf<Classes, Routes>, AppSnapshotShape<Instances<BuiltInModels & Classes>, StoresOf<Group, StoreInstances<Custom>>, PageOf<Routes>>> & {
+        readonly models: Instances<BuiltInModels & Classes>;
+        readonly stores: StoresOf<Group, StoreInstances<Custom>>;
+        pressKey(key: string): Promise<void> | undefined;
+    };
+    readonly definition: AppDefinition<Group, Custom, Classes, Routes>;
+};
+export declare function defineApp<Group extends Tables, Classes extends Record<string, ModelClassLike>, Routes extends readonly RouteDefinition[], Custom extends StoreClasses = Record<never, never>>(definition: AppDefinition<Group, Custom, Classes, Routes>): DefinedApp<Group, Classes, Routes, Custom>;

package/dist/app.js

@@ -0,0 +1,266 @@
+import { z } from 'zod';
+import { viewerOf } from "./access.js";
+import { AppStore } from "./appInfo.js";
+import { SessionStore } from "./auth/sessionStore.js";
+import { realClock } from "./clock.js";
+import { ActionsStore } from "./actions.js";
+import { Account } from "./builtins/Account.js";
+import { AppSettings } from "./builtins/AppSettings.js";
+import { BUILT_IN_GROUPS, builtInActions } from "./builtins/actions.js";
+import { Palette } from "./builtins/Palette.js";
+import { SignIn } from "./builtins/SignIn.js";
+import { Toasts } from "./builtins/Toasts.js";
+import { PageStore } from "./page.js";
+import { assertNotBuilding, snapshotsOf } from "./store.js";
+import { ModelBase, command, createModels, modelSnapshotsOf, parseMessage, sendMessage } from "./model.js";
+import { isRoutedPath, pageIds, registerRoutes } from "./routes.js";
+import { PublicTableStore, TableStore, publicStoreName } from "./tables.js";
+function dataStores(tables, api, cache, viewer) {
+    const stores = { tables: {}, publicViews: {} };
+    for (const [key, table] of Object.entries(tables)) {
+        const found = Reflect.get(api, key);
+        const tableApi = found;
+        const publicView = table.public.length > 0
+            ? new PublicTableStore(table, { api: tableApi, cache })
+            : undefined;
+        if (publicView !== undefined) {
+            stores.publicViews[publicStoreName(key)] = publicView;
+        }
+        if (table.access.read !== 'server') {
+            stores.tables[key] = new TableStore(table, {
+                api: tableApi,
+                cache,
+                viewer,
+                ...(publicView === undefined ? {} : { publicView })
+            });
+        }
+    }
+    return stores;
+}
+function clashOf(groups) {
+    const seen = new Set();
+    for (const name of groups.flat()) {
+        if (seen.has(name))
+            return name;
+        seen.add(name);
+    }
+    return undefined;
+}
+const builtInModels = {
+    account: Account,
+    appSettings: AppSettings,
+    palette: Palette,
+    signIn: SignIn
+};
+const appPathInput = z.custom((value) => typeof value === 'string' && isRoutedPath(value), { error: 'Not a page in src/routes.tsx' });
+export function defineApp(definition) {
+    const pages = new Set(pageIds(definition.routes));
+    registerRoutes(definition.routes);
+    if (Object.hasOwn(definition.models, 'app')) {
+        throw new Error('A model can\'t be called "app": app.navigate is the built-in command that changes the page');
+    }
+    for (const name of Object.keys(builtInModels)) {
+        if (Object.hasOwn(definition.models, name)) {
+            throw new Error(`${name} is a built-in model of @trypattern/sdk: its state, answers and commands come from Pattern. Name yours for what it holds.`);
+        }
+    }
+    return class App {
+        static definition = definition;
+        router;
+        models;
+        stores;
+        #commandGroups;
+        #page = new PageStore();
+        #cache;
+        #gate;
+        #session;
+        #data;
+        #navigations = new Set();
+        #repeats = new Set();
+        #clock;
+        #failures = [];
+        #path;
+        #user;
+        constructor(router, { api, cache, gate, clock = realClock() }) {
+            this.router = router;
+            this.#cache = cache;
+            this.#gate = gate;
+            this.#clock = clock;
+            const session = new SessionStore({ api: api.session });
+            const app = new AppStore({
+                api: api.app,
+                remembered: cache.scope('app.title', z.string())
+            });
+            const data = dataStores(definition.tables, api.tables, cache, () => viewerOf(session.state.user));
+            const custom = Object.fromEntries(Object.entries(definition.stores ?? {}).map(([key, Store]) => [
+                key,
+                new Store(cache.persisted(`stores.${key}`), api.services)
+            ]));
+            const toasts = new Toasts(cache.persisted('stores.toasts'), {});
+            const clash = clashOf([
+                ['session', 'app', 'actions', 'toasts', 'page'],
+                Object.keys(data.tables),
+                Object.keys(data.publicViews),
+                Object.keys(custom)
+            ]);
+            if (clash !== undefined) {
+                throw new Error(`Two stores are called "${clash}". The built-in session, app, actions, toasts and page stores, each table, each table's public view and each store in src/stores/index.ts need their own name.`);
+            }
+            const actions = new ActionsStore(this.#page, [...(definition.actions ?? []), ...builtInActions], [
+                ...(definition.actionGroups ?? []),
+                ...BUILT_IN_GROUPS.filter((group) => !(definition.actionGroups ?? []).includes(group))
+            ], (message) => this.#runAction(message));
+            this.stores = {
+                session,
+                app,
+                actions,
+                toasts,
+                page: this.#page,
+                ...data.tables,
+                ...data.publicViews,
+                ...custom
+            };
+            this.#session = session;
+            this.#data = data;
+            const services = {
+                navigate: (to) => {
+                    assertNotBuilding('navigate');
+                    return this.#navigate(to);
+                },
+                every: (ms, run) => {
+                    assertNotBuilding('repeat');
+                    return this.#every(ms, run);
+                }
+            };
+            this.models = createModels({ ...builtInModels, ...definition.models }, this.stores, services, (model) => cache.persisted(model));
+            this.#commandGroups = {
+                ...this.models,
+                app: {
+                    navigate: command({ input: { to: appPathInput } }, ({ to }) => this.#navigate(to)),
+                    pressKey: command({ input: { key: z.string() } }, ({ key }) => this.pressKey(key))
+                }
+            };
+            this.#path = router.state.location.pathname;
+            this.#page.moved(this.#currentPage(), this.#currentParams());
+            actions.watch(this.models);
+            this.#user = session.state.user?.id ?? null;
+            router.subscribe(() => this.#routeChanged());
+            session.subscribe(() => this.#sessionChanged());
+            void session.confirm();
+            void app.load();
+            for (const view of Object.values(data.publicViews))
+                void view.load();
+            this.#loadReadableTables();
+        }
+        send(command) {
+            return this.#send(command);
+        }
+        pressKey(key) {
+            return this.stores.actions.pressKey(key);
+        }
+        parse(raw) {
+            return parseMessage(raw, this.#commandGroups);
+        }
+        getSnapshot() {
+            return {
+                page: this.#currentPage(),
+                path: this.router.state.location.pathname,
+                models: modelSnapshotsOf(this.models),
+                stores: snapshotsOf(this.stores)
+            };
+        }
+        tick() {
+            this.#clock.tick();
+        }
+        async whenIdle() {
+            do {
+                await Promise.allSettled(this.#navigations);
+                await this.#gate.whenIdle();
+            } while (this.#navigations.size > 0);
+            const failure = this.#failures.shift();
+            if (failure !== undefined)
+                throw failure;
+        }
+        #runAction(message) {
+            const parsed = this.parse(message);
+            if ('error' in parsed) {
+                return Promise.reject(new Error(String(parsed.error)));
+            }
+            return this.#send(parsed);
+        }
+        #send(command) {
+            return sendMessage(this.#commandGroups, command).catch((failure) => {
+                this.#failures.push(failure);
+            });
+        }
+        #currentPage() {
+            const id = this.router.state.matches.at(-1)?.route.id;
+            return id !== undefined && pages.has(id) ? id : null;
+        }
+        #currentParams() {
+            return this.router.state.matches.at(-1)?.params ?? {};
+        }
+        #navigate(to) {
+            const navigation = this.router.navigate(to).finally(() => {
+                this.#navigations.delete(navigation);
+            });
+            this.#navigations.add(navigation);
+            return navigation;
+        }
+        #every(ms, run) {
+            const stop = this.#clock.every(ms, () => {
+                void Promise.resolve(run()).catch((failure) => {
+                    this.#failures.push(failure);
+                });
+            });
+            const remove = () => {
+                stop();
+                this.#repeats.delete(remove);
+            };
+            this.#repeats.add(remove);
+            return remove;
+        }
+        #stopRepeats() {
+            for (const stop of [...this.#repeats])
+                stop();
+        }
+        #routeChanged() {
+            const path = this.router.state.location.pathname;
+            if (path === this.#path)
+                return;
+            this.#path = path;
+            this.#stopRepeats();
+            this.#page.moved(this.#currentPage(), this.#currentParams());
+            this.#openCurrentModel();
+        }
+        #sessionChanged() {
+            const user = this.#session.state.user?.id ?? null;
+            if (user === this.#user)
+                return;
+            this.#user = user;
+            this.#stopRepeats();
+            this.#cache.clear();
+            for (const store of Object.values(this.#data.tables))
+                store.forget();
+            this.#loadReadableTables();
+        }
+        #loadReadableTables() {
+            for (const store of Object.values(this.#data.tables))
+                void store.load();
+            this.#openCurrentModel();
+        }
+        #openCurrentModel() {
+            const match = this.router.state.matches.at(-1);
+            if (match === undefined)
+                return;
+            const model = Object.hasOwn(this.models, match.route.id)
+                ? Reflect.get(this.models, match.route.id)
+                : undefined;
+            if (!(model instanceof ModelBase))
+                return;
+            void Promise.resolve(model.onPageOpen(match.params)).catch((failure) => {
+                this.#failures.push(failure);
+            });
+        }
+    };
+}

package/dist/appInfo.d.ts

@@ -0,0 +1,35 @@
+import type { AppInfo } from './appTitle.ts';
+import type { Cached } from './cache.ts';
+import type { Gate } from './gate.ts';
+import type { MemoryApiOptions } from './memoryApi.ts';
+import { StoreBase } from './store.ts';
+export type AppInfoApi = {
+    read: () => Promise<AppInfo>;
+    rename: (title: string) => Promise<AppInfo>;
+};
+export type AppInfoCall = 'read' | 'rename';
+export declare const appInfoCalls: readonly AppInfoCall[];
+export declare class HttpAppInfoApi implements AppInfoApi {
+    #private;
+    constructor(gate: Gate);
+    read(): Promise<AppInfo>;
+    rename(title: string): Promise<AppInfo>;
+}
+export declare class MemoryAppInfoApi implements AppInfoApi {
+    #private;
+    constructor(title: string, options: MemoryApiOptions);
+    read(): Promise<AppInfo>;
+    rename(title: string): Promise<AppInfo>;
+}
+export type AppState = {
+    title: string;
+};
+export declare class AppStore extends StoreBase<AppState, {
+    api: AppInfoApi;
+    remembered: Cached<string>;
+}> {
+    #private;
+    protected initialState(): AppState;
+    load(): Promise<void>;
+    rename(title: string): Promise<void>;
+}

package/dist/appInfo.js

@@ -0,0 +1,67 @@
+import { appInfo } from "./appTitle.js";
+import { MemoryServer } from "./memoryApi.js";
+import { StoreBase } from "./store.js";
+export const appInfoCalls = ['read', 'rename'];
+export class HttpAppInfoApi {
+    #gate;
+    constructor(gate) {
+        this.#gate = gate;
+    }
+    read() {
+        return this.#gate.pass('app.read', async () => {
+            const response = await fetch('/api/app');
+            if (!response.ok)
+                throw new Error('app.read failed');
+            return appInfo.parse(await response.json());
+        });
+    }
+    rename(title) {
+        return this.#gate.pass('app.rename', async () => {
+            const response = await fetch('/api/app', {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ title })
+            });
+            if (!response.ok)
+                throw new Error('app.rename failed');
+            return appInfo.parse(await response.json());
+        });
+    }
+}
+export class MemoryAppInfoApi {
+    #server;
+    #title;
+    constructor(title, options) {
+        this.#server = new MemoryServer('app', options);
+        this.#title = title;
+    }
+    read() {
+        return this.#server.reply('read', () => ({ title: this.#title }));
+    }
+    rename(title) {
+        return this.#server.reply('rename', () => {
+            this.#title = title;
+            return { title };
+        });
+    }
+}
+export class AppStore extends StoreBase {
+    initialState() {
+        return { title: this.deps.remembered.read() ?? '' };
+    }
+    async load() {
+        try {
+            this.#keep(await this.deps.api.read());
+        }
+        catch {
+            return;
+        }
+    }
+    async rename(title) {
+        this.#keep(await this.deps.api.rename(title));
+    }
+    #keep({ title }) {
+        this.set({ title });
+        this.deps.remembered.write(title);
+    }
+}

package/dist/appTitle.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const appTitle: z.ZodString;
+export declare const appInfo: z.ZodObject<{
+    title: z.ZodString;
+}, z.core.$strip>;
+export type AppInfo = z.output<typeof appInfo>;

package/dist/appTitle.js

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export const appTitle = z.string().trim().min(1).max(60);
+export const appInfo = z.object({ title: z.string() });

package/dist/appearance.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const appearance: z.ZodEnum<{
+    system: "system";
+    light: "light";
+    dark: "dark";
+}>;
+export type Appearance = z.infer<typeof appearance>;

package/dist/appearance.js

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export const appearance = z.enum(['system', 'light', 'dark']);

package/dist/auth/sessionApi.d.ts

@@ -0,0 +1,41 @@
+import type { Gate } from '../gate.ts';
+import type { MemoryApiOptions } from '../memoryApi.ts';
+import type { User } from './user.ts';
+export type SessionApi = {
+    rememberedUser: () => User | undefined;
+    me: () => Promise<User | undefined>;
+    devSignIn: (email: string) => Promise<User>;
+    sendEmailCode: (email: string) => Promise<EmailCodeOutcome>;
+    verifyEmailCode: (code: string) => Promise<User | undefined>;
+    signOut: () => Promise<void>;
+    startGoogleSignIn: () => void;
+    onSignedOut: (listener: () => void) => void;
+};
+export type EmailCodeOutcome = 'sent' | 'refused';
+export type SessionCall = 'me' | 'devSignIn' | 'sendEmailCode' | 'verifyEmailCode' | 'signOut';
+export declare const sessionCalls: readonly SessionCall[];
+export declare class HttpSessionApi implements SessionApi {
+    #private;
+    constructor(gate: Gate);
+    rememberedUser(): User | undefined;
+    me(): Promise<User | undefined>;
+    devSignIn(email: string): Promise<User>;
+    sendEmailCode(email: string): Promise<EmailCodeOutcome>;
+    verifyEmailCode(code: string): Promise<User | undefined>;
+    signOut(): Promise<void>;
+    startGoogleSignIn(): void;
+    onSignedOut(listener: () => void): void;
+    reportSignedOut(): void;
+}
+export declare class MemorySessionApi implements SessionApi {
+    #private;
+    constructor(signedInAs: string | null, admins: readonly string[], options: MemoryApiOptions);
+    rememberedUser(): User | undefined;
+    me(): Promise<User | undefined>;
+    devSignIn(email: string): Promise<User>;
+    sendEmailCode(email: string): Promise<EmailCodeOutcome>;
+    verifyEmailCode(code: string): Promise<User | undefined>;
+    signOut(): Promise<void>;
+    startGoogleSignIn(): void;
+    onSignedOut(): void;
+}