@trypattern/sdk 0.0.0-stage → 0.1.0

package/dist/store.js

@@ -0,0 +1,198 @@
+import { restore } from "./state.js";
+import { Subscribers } from "./subscribers.js";
+export function isDevelopment() {
+    return import.meta.env?.DEV === true;
+}
+export function plainJsonProblem(value, path) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return undefined;
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? undefined : `${path} is ${String(value)}`;
+    }
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const problem = plainJsonProblem(item, `${path}[${index}]`);
+            if (problem !== undefined)
+                return problem;
+        }
+        return undefined;
+    }
+    if (typeof value === 'object') {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return `${path} is a ${value.constructor.name}`;
+        }
+        for (const [key, item] of Object.entries(value)) {
+            const problem = plainJsonProblem(item, `${path}.${key}`);
+            if (problem !== undefined)
+                return problem;
+        }
+        return undefined;
+    }
+    return `${path} is a ${typeof value}`;
+}
+export function keepEqualParts(previous, next) {
+    if (Object.is(previous, next))
+        return next;
+    if (typeof previous !== 'object' ||
+        typeof next !== 'object' ||
+        previous === null ||
+        next === null ||
+        Array.isArray(previous) !== Array.isArray(next)) {
+        return next;
+    }
+    const previousKeys = Object.keys(previous);
+    const nextKeys = Object.keys(next);
+    let allSame = previousKeys.length === nextKeys.length;
+    const merged = Array.isArray(next)
+        ? Array.from({ length: next.length })
+        : {};
+    for (const key of nextKeys) {
+        const kept = keepEqualParts(Reflect.get(previous, key), Reflect.get(next, key));
+        merged[key] = kept;
+        if (!Object.is(kept, Reflect.get(previous, key)))
+            allSame = false;
+    }
+    return allSame ? previous : merged;
+}
+let tracking;
+let building = 0;
+const unproxied = new WeakMap();
+export function tracked(run) {
+    const outer = tracking;
+    const reads = new Map();
+    const session = { reads, isLive: true };
+    tracking = session;
+    try {
+        const value = run();
+        const plain = typeof value === 'object' && value !== null
+            ? unproxied.get(value)
+            : undefined;
+        return { value: plain ?? value, reads };
+    }
+    finally {
+        session.isLive = false;
+        tracking = outer;
+    }
+}
+export function mergeReads(from) {
+    if (tracking === undefined)
+        return;
+    for (const [store, keys] of from) {
+        const into = tracking.reads.get(store) ?? new Map();
+        for (const [key, value] of keys)
+            into.set(key, value);
+        tracking.reads.set(store, into);
+    }
+}
+export function readsAreCurrent(reads) {
+    for (const [store, keys] of reads) {
+        const state = store.currentState;
+        for (const [key, value] of keys) {
+            if (!Object.is(Reflect.get(state, key), value))
+                return false;
+        }
+    }
+    return true;
+}
+export function whileBuilding(run) {
+    building += 1;
+    try {
+        return run();
+    }
+    finally {
+        building -= 1;
+    }
+}
+export function assertNotBuilding(what) {
+    if (building > 0) {
+        throw new Error(`A getter tried to ${what}. Getters only work answers out from state and stores; put changes in a command.`);
+    }
+}
+function hasChanges(state, patch) {
+    return Object.entries(patch).some(([key, value]) => !Object.is(state[key], value));
+}
+export class StoreBase {
+    deps;
+    #state;
+    #subscribers = new Subscribers();
+    constructor(...args) {
+        this.deps = args[0];
+    }
+    get state() {
+        const state = this.currentState;
+        const session = tracking;
+        if (session === undefined)
+            return state;
+        const reads = session.reads.get(this) ?? new Map();
+        session.reads.set(this, reads);
+        const proxy = new Proxy(state, {
+            get(target, key) {
+                const value = Reflect.get(target, key);
+                if (session.isLive && typeof key === 'string')
+                    reads.set(key, value);
+                return value;
+            }
+        });
+        unproxied.set(proxy, state);
+        return proxy;
+    }
+    get currentState() {
+        this.#state ??= this.initialState();
+        return this.#state;
+    }
+    subscribe = (listener) => this.#subscribers.subscribe(listener);
+    set(patch) {
+        assertNotBuilding(`change ${this.constructor.name}`);
+        const state = this.currentState;
+        if (!hasChanges(state, patch))
+            return;
+        this.#state = { ...state, ...patch };
+        if (isDevelopment()) {
+            const problem = plainJsonProblem(this.#state, 'state');
+            if (problem !== undefined) {
+                throw new Error(`${this.constructor.name} state must be plain JSON, because flows compare it and the cache stores it: ${problem}`);
+            }
+        }
+        this.changed();
+    }
+    changed() {
+        this.#subscribers.notify();
+    }
+}
+export class DeclaredStore extends StoreBase {
+    initialState() {
+        throw new Error(`${this.constructor.name} must extend Store({ state }) so its first state comes from the config`);
+    }
+}
+export function Store(config) {
+    const persist = config.persist ?? [];
+    class Declared extends DeclaredStore {
+        static config = config;
+        #persisted;
+        constructor(persisted) {
+            super();
+            this.#persisted = persisted;
+        }
+        initialState() {
+            return restore(config.state ?? {}, persist, this.#persisted);
+        }
+        set(patch) {
+            super.set(patch);
+            for (const key of persist) {
+                if (key in patch)
+                    this.#persisted.write(key, this.state[key]);
+            }
+        }
+    }
+    return Declared;
+}
+export function snapshotsOf(group) {
+    const entries = Object.entries(group).map(([key, store]) => [
+        key,
+        store.state
+    ]);
+    return Object.fromEntries(entries);
+}

package/dist/subscribers.d.ts

@@ -0,0 +1,5 @@
+export declare class Subscribers {
+    #private;
+    readonly subscribe: (listener: () => void) => (() => void);
+    notify(): void;
+}

package/dist/subscribers.js

@@ -0,0 +1,13 @@
+export class Subscribers {
+    #listeners = new Set();
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    };
+    notify() {
+        for (const listener of this.#listeners)
+            listener();
+    }
+}

package/dist/table.d.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import type { SameOnTheWire } from './wire.ts';
+export type Value = string | number | boolean | null;
+export type Columns = Record<string, z.ZodType<Value>>;
+export type Level = 'anyone' | 'signedIn' | 'owner' | 'admin' | 'server';
+export type Access = {
+    readonly read: Level;
+    readonly create: Level;
+    readonly update: Level;
+    readonly delete: Level;
+};
+export type Writes = 'optimistic' | 'confirmed';
+export type TableDefinition = {
+    readonly columns: Columns;
+    readonly access: Access;
+    readonly writes: Writes;
+    readonly owned?: boolean;
+    readonly public?: readonly string[];
+    readonly unique?: readonly (readonly string[])[];
+};
+type OwnerColumn<Owned> = [Owned] extends [true] ? {
+    ownerId: z.ZodString;
+} : Record<never, never>;
+export type Table = {
+    readonly name: string;
+    readonly columns: Columns;
+    readonly access: Access;
+    readonly writes: Writes;
+    readonly owned: boolean;
+    readonly public: readonly string[];
+    readonly unique: readonly (readonly string[])[];
+    readonly fields: z.ZodObject<Columns>;
+    readonly incoming: z.ZodObject<{
+        id: z.ZodString;
+    } & Columns>;
+    readonly row: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodString;
+    } & Columns>;
+    readonly publicRow: z.ZodObject<{
+        id: z.ZodString;
+    } & Columns>;
+};
+export type TableOf<Name extends string, Definition extends TableDefinition> = {
+    readonly name: Name;
+    readonly columns: Definition['columns'];
+    readonly access: Definition['access'];
+    readonly writes: Definition['writes'];
+    readonly owned: Definition['owned'] extends true ? true : false;
+    readonly public: readonly PublicColumn<Definition>[];
+    readonly unique: readonly (readonly string[])[];
+    readonly fields: z.ZodObject<Definition['columns']>;
+    readonly incoming: z.ZodObject<{
+        id: z.ZodString;
+    } & Definition['columns']>;
+    readonly row: z.ZodObject<{
+        id: z.ZodString;
+        createdAt: z.ZodString;
+    } & OwnerColumn<Definition['owned']> & Definition['columns']>;
+    readonly publicRow: z.ZodObject<{
+        id: z.ZodString;
+    } & Pick<{
+        createdAt: z.ZodString;
+    } & Definition['columns'], PublicColumn<Definition>>>;
+};
+type PublicColumn<Definition extends TableDefinition> = Definition['public'] extends readonly (infer Column)[] ? Column & (keyof Definition['columns'] | 'createdAt') & string : never;
+export type Fields<T extends Table> = z.output<T['fields']>;
+type OwnerOf<T extends Table> = T['owned'] extends true ? {
+    ownerId: string;
+} : Record<never, never>;
+export type Row<T extends Table> = {
+    id: string;
+    createdAt: string;
+} & OwnerOf<T> & Fields<T>;
+export type PublicRow<T extends Table> = {
+    id: string;
+} & Pick<{
+    createdAt: string;
+} & Fields<T>, T['public'][number] & ('createdAt' | keyof Fields<T>)>;
+export type Tables = Record<string, Table>;
+export type SeedRow<T extends Table> = {
+    id: string;
+} & (T['owned'] extends true ? {
+    owner: string;
+} : Record<never, never>) & Fields<T>;
+export type Seed<Group extends Tables> = {
+    [Key in keyof Group]?: readonly SeedRow<Group[Key]>[];
+};
+export type TablesOf<Definitions extends Record<string, DraftTable>> = {
+    [Key in keyof Definitions & string]: Definitions[Key] extends TableDefinition ? TableOf<Key, Definitions[Key]> : Table;
+};
+type DraftTable = {
+    readonly columns: Columns;
+    readonly access?: Partial<Access>;
+    readonly writes?: Writes;
+    readonly owned?: boolean;
+    readonly public?: readonly string[];
+    readonly unique?: readonly (readonly string[])[];
+};
+type StaticTypeError<Message extends string> = Message;
+type IsOwned<Definition> = Definition extends {
+    readonly owned: true;
+} ? true : false;
+type HasUnique<Definition> = Definition extends {
+    readonly unique: readonly [unknown, ...unknown[]];
+} ? true : false;
+type ReadOf<Definition> = Definition extends {
+    readonly access: {
+        readonly read: infer Read;
+    };
+} ? Read : never;
+type ColumnOf<Definition> = Definition extends {
+    readonly columns: infer C;
+} ? keyof C & string : never;
+type OwnerNeedsOwned = StaticTypeError<"'owner' needs owned: true on this table, so every row records who made it">;
+type CreateIsNeverOwner = StaticTypeError<"create can't be 'owner': nobody owns a row before it exists. Use 'signedIn' and the person who creates it becomes its owner">;
+type OwnedNeedsSignedInCreate = StaticTypeError<"An owned table can't let anyone create rows: a signed-out visitor has no account to own the row. Use 'signedIn'">;
+type UniqueNeedsConfirmed = StaticTypeError<"This table has a unique constraint, so the server can refuse a write. Declare writes: 'confirmed' so the screen waits for the server instead of showing a row that then disappears">;
+type PublicNeedsPrivateRead = StaticTypeError<"public only matters when read is stricter than 'anyone': with read: 'anyone' every column is already public">;
+type AccessIsRequired = StaticTypeError<"Every table says who may read, create, update and delete its rows: add access: { read, create, update, delete }, each 'anyone', 'signedIn', 'owner', 'admin' or 'server'">;
+type EveryOperation = StaticTypeError<'access names all four operations: read, create, update and delete'>;
+type WritesIsRequired = StaticTypeError<"Every table says whether a write shows at once or waits for the server: add writes: 'optimistic' or writes: 'confirmed'">;
+type Missing<Shape, Required extends string, Message> = {
+    [Key in Exclude<Required, keyof Shape>]: Message;
+};
+type OwnerIdIsPattern = StaticTypeError<'Pattern adds ownerId to owned tables and fills it from the session: remove this column and set owned: true'>;
+type CheckedLevel<Definition, Operation, Chosen> = Chosen extends 'owner' ? Operation extends 'create' ? CreateIsNeverOwner : IsOwned<Definition> extends true ? Chosen : OwnerNeedsOwned : Operation extends 'create' ? Chosen extends 'anyone' ? IsOwned<Definition> extends true ? OwnedNeedsSignedInCreate : Chosen : Chosen : Chosen;
+type CheckedAccess<Definition, A> = {
+    [Operation in keyof A]: CheckedLevel<Definition, Operation, A[Operation]>;
+} & Missing<A, keyof Access, EveryOperation>;
+type CheckedColumns<C> = {
+    [Key in keyof C]: Key extends 'ownerId' ? OwnerIdIsPattern : C[Key];
+};
+type CheckedTable<Definition> = {
+    [Key in keyof Definition]: Key extends 'columns' ? CheckedColumns<SameOnTheWire<Definition[Key] & z.ZodRawShape>> : Key extends 'access' ? CheckedAccess<Definition, Definition[Key]> : Key extends 'writes' ? HasUnique<Definition> extends true ? Definition[Key] extends 'confirmed' ? Definition[Key] : UniqueNeedsConfirmed : Definition[Key] : Key extends 'public' ? ReadOf<Definition> extends 'anyone' ? PublicNeedsPrivateRead : Definition[Key] & readonly (ColumnOf<Definition> | 'createdAt')[] : Key extends 'unique' ? Definition[Key] & readonly (readonly ColumnOf<Definition>[])[] : Definition[Key];
+} & Missing<Definition, 'access', AccessIsRequired> & Missing<Definition, 'writes', WritesIsRequired>;
+export declare function defineTables<const Definitions extends Record<string, DraftTable>>(definitions: {
+    [Key in keyof Definitions]: CheckedTable<Definitions[Key]>;
+}): TablesOf<Definitions>;
+export declare function ownerIdOf(email: string): string;
+export declare function seededRows(seed: Seed<Tables>, name: string): readonly Row<Table>[];
+export declare function snakeCase(name: string): string;
+export {};

package/dist/table.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+const NAME = /^[a-z][a-zA-Z0-9]*$/;
+const RESERVED = ['id', 'createdAt', 'ownerId'];
+const RESERVED_TABLES = ['users', 'sessions', 'session'];
+const SEEDED_AT = Date.UTC(2000, 0, 1);
+function problemIn(name, definition) {
+    const { access, columns } = definition;
+    const known = Object.keys(columns);
+    if (access.create === 'owner') {
+        return `Table "${name}": create can't be 'owner', use 'signedIn'`;
+    }
+    if (definition.owned !== true && Object.values(access).includes('owner')) {
+        return `Table "${name}" uses 'owner' but is not owned: true`;
+    }
+    if (definition.owned === true && access.create === 'anyone') {
+        return `Table "${name}" is owned, so create must not be 'anyone'`;
+    }
+    const unknown = [
+        ...(definition.public ?? []).filter((column) => column !== 'createdAt'),
+        ...(definition.unique ?? []).flat()
+    ].find((column) => !known.includes(column));
+    if (unknown !== undefined) {
+        return `Table "${name}" names "${unknown}", which is not one of its columns`;
+    }
+    if ((definition.unique ?? []).length > 0 &&
+        definition.writes !== 'confirmed') {
+        return `Table "${name}" has a unique constraint, so writes must be 'confirmed'`;
+    }
+    return undefined;
+}
+function table(name, definition) {
+    const { columns } = definition;
+    for (const key of [name, ...Object.keys(columns)]) {
+        if (!NAME.test(key)) {
+            throw new Error(`"${key}" can't name a table or column: use camelCase letters and digits`);
+        }
+    }
+    if (RESERVED_TABLES.includes(name)) {
+        throw new Error(`A table can't be called "${name}": Pattern keeps its own ${name} for sign-in`);
+    }
+    const reserved = RESERVED.find((key) => key in columns);
+    if (reserved !== undefined) {
+        throw new Error(`Table "${name}" can't have a "${reserved}" column: Pattern adds it`);
+    }
+    const problem = problemIn(name, definition);
+    if (problem !== undefined)
+        throw new Error(problem);
+    const owned = definition.owned === true;
+    const publicColumns = definition.public ?? [];
+    return {
+        name,
+        columns,
+        access: definition.access,
+        writes: definition.writes,
+        owned,
+        public: publicColumns,
+        unique: definition.unique ?? [],
+        fields: z.object(columns),
+        incoming: z.object({ id: z.string(), ...columns }),
+        row: z.object({
+            id: z.string(),
+            createdAt: z.string(),
+            ...(owned ? { ownerId: z.string() } : {}),
+            ...columns
+        }),
+        publicRow: z.object({
+            id: z.string(),
+            ...Object.fromEntries(publicColumns.map((column) => [
+                column,
+                column === 'createdAt' ? z.string() : columns[column]
+            ]))
+        })
+    };
+}
+export function defineTables(definitions) {
+    return Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [name, table(name, definition)]));
+}
+export function ownerIdOf(email) {
+    return `user-${email.toLowerCase()}`;
+}
+export function seededRows(seed, name) {
+    const rows = Reflect.get(seed, name) ?? [];
+    return rows.map(({ owner, ...row }, index) => ({
+        ...row,
+        ...(typeof owner === 'string' ? { ownerId: ownerIdOf(owner) } : {}),
+        createdAt: new Date(SEEDED_AT + index * 1000).toISOString()
+    }));
+}
+export function snakeCase(name) {
+    return name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}

package/dist/tables.d.ts

@@ -0,0 +1,77 @@
+import type { Viewer, WriteOutcome } from './access.ts';
+import type { Cache, Cached } from './cache.ts';
+import { EntityStore, entityCalls } from './entityStore.ts';
+import type { EntityApi } from './entityStore.ts';
+import type { Gate } from './gate.ts';
+import type { MemoryApiOptions } from './memoryApi.ts';
+import { StoreBase } from './store.ts';
+import type { Fields, PublicRow, Row, Seed, Table, Tables } from './table.ts';
+export type TableApi<T extends Table> = EntityApi<Row<T>> & {
+    listPublic: () => Promise<readonly PublicRow<T>[]>;
+};
+export type TablesApi<Group extends Tables> = {
+    [Key in keyof Group]: TableApi<Group[Key]>;
+};
+export type TableCall<Group extends Tables> = `${keyof Group & string}.${(typeof entityCalls)[number] | 'listPublic'}`;
+export type CurrentViewer = () => Viewer | null;
+export declare class HttpTableApi<T extends Table> implements TableApi<T> {
+    #private;
+    constructor(table: T, gate: Gate, onSignedOut: () => void, base?: string);
+    list(): Promise<readonly Row<T>[]>;
+    listPublic(): Promise<readonly PublicRow<T>[]>;
+    create(row: Row<T>): Promise<Row<T>>;
+    update(row: Row<T>): Promise<Row<T>>;
+    remove(id: string): Promise<void>;
+}
+type AnyRow = Readonly<Record<string, unknown>> & {
+    id: string;
+    ownerId?: string;
+};
+export declare class MemoryTableApi<T extends Table> implements TableApi<T> {
+    #private;
+    constructor(table: T, seed: readonly AnyRow[], viewer: CurrentViewer, options: MemoryApiOptions);
+    list(): Promise<readonly Row<T>[]>;
+    listPublic(): Promise<readonly PublicRow<T>[]>;
+    create(row: Row<T>): Promise<Row<T>>;
+    update(row: Row<T>): Promise<Row<T>>;
+    remove(id: string): Promise<void>;
+}
+export declare function httpTables<Group extends Tables>(tables: Group, gate: Gate, onSignedOut: () => void): TablesApi<Group>;
+export declare function memoryTables<Group extends Tables>(tables: Group, seed: Seed<Group>, viewer: CurrentViewer, options: MemoryApiOptions): TablesApi<Group>;
+export declare function tableCalls<Group extends Tables>(tables: Group): readonly TableCall<Group>[];
+export declare function publicStoreName(table: string): string;
+export type PublicSnapshot<Item> = {
+    status: 'idle' | 'loading' | 'ready' | 'failed';
+    items: readonly Item[];
+};
+type PublicDeps<Item> = {
+    list: () => Promise<readonly Item[]>;
+    cache: Cached<readonly Item[]>;
+};
+export declare class PublicTableStore<T extends Table> extends StoreBase<PublicSnapshot<PublicRow<T>>, PublicDeps<PublicRow<T>>> {
+    #private;
+    constructor(table: T, { api, cache }: {
+        api: TableApi<T>;
+        cache: Cache;
+    });
+    protected initialState(): PublicSnapshot<PublicRow<T>>;
+    load(): Promise<void>;
+}
+type TableDeps<T extends Table> = {
+    api: TableApi<T>;
+    cache: Cache;
+    viewer: CurrentViewer;
+    publicView?: {
+        load: () => Promise<void>;
+    };
+};
+export declare class TableStore<T extends Table> extends EntityStore<Row<T>> {
+    #private;
+    constructor(table: T, { api, cache, viewer, publicView }: TableDeps<T>);
+    get mayRead(): boolean;
+    load(): Promise<void>;
+    create(fields: Fields<T>): Promise<WriteOutcome>;
+    update(row: Row<T>): Promise<WriteOutcome>;
+    remove(id: string): Promise<WriteOutcome>;
+}
+export {};