@trylight/app 0.1.3 → 0.1.4

package/README.md

@@ -8,7 +8,7 @@ unchanged; entities and the schema sync are new here.
 | Import | What |
 |---|---|
 | `@trylight/app/schema` | `entity(name, columns, access)`: a Drizzle table plus `id`, `created_at`, `updated_at`, `created_by`, `field_sources`; `lightChanges` (the audit table); `lightImages` (the app's copy of its logos and photos); `fieldSource` (the `{url, evidence}` schema) |
-| `@trylight/app` | `createApp<typeof contracts>()` → `app.table(entity)` (`list/get/create/update/delete`, `useList/useGet/useCreate/useUpdate/useDelete`, typed by the entity passed), `app.contracts` (`useInvocation`), and `imageSrc(url)` (where a logo or photo loads from) |
+| `@trylight/app` | `createApp<typeof contracts>()` → `app.table(entity)` (`list/get/create/update/delete`, `useList/useGet/useCreate/useUpdate/useDelete`, typed by the entity passed; `useList(...).rows` is never undefined), `app.contracts` (`useInvocation`), and `imageSrc(url)` (where a logo or photo loads from) |
 | `@trylight/app/server` | `createLightServer({ schema, contracts })` → `light.db` (Drizzle), `light.session(request)`, `light.signIn(email, password)`, and the route handlers `light.entities`, `light.image`, `light.invoke.handler`, `light.chat` |
 | `@trylight/app/platform` | the door for server functions, framing, analytics/error policies, the pane bridge |
 | `@trylight/app/vite` | `lightDb()`: the dev server syncs `db/schema` into the database on every change |
@@ -70,7 +70,7 @@ fails while `db/schema` has changes no migration holds.
 `src/db/audit.ts`, in Postgres itself. Every entity table has a row trigger
 that records each insert, update, delete and truncate in `light_changes` (the
 new row, `{ column: { from, to } }`, or the old row), whoever wrote it: the
-actor is `light.actor_kind/_id/_name`, which the entities route and Plaza's
+actor is `light.actor_kind/_id/_name`, which the entities route and the platform's
 `mii db write` set per transaction, or else the database role. A migration
 that drops a table or column or changes a column's type first copies what it
 destroys into `light_archive` (`light_archive_values`, called at the top of

package/dist/client.d.ts

@@ -23,8 +23,175 @@ declare function tableClient<T extends Entity>(entity: T): {
     create: (data: NewRow<T>) => Promise<Row<T>>;
     update: (id: string, patch: Patch<T>) => Promise<Row<T>>;
     delete: (id: string) => Promise<void>;
-    /** The rows, cached per options; refetched after any write to this table. */
-    useList: (options?: ListOptions<Row<T>>) => import("@tanstack/react-query").UseQueryResult<(T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never)[], EntityError>;
+    /**
+     * The query (`isPending`, `isError`, `error`, `refetch`) and its `rows`,
+     * cached per options and refetched after any write to this table. `rows`
+     * is never undefined: empty until the first answer, and the same array
+     * until the rows change, so it can sit in a hook's dependencies.
+     */
+    useList: (options?: ListOptions<Row<T>>) => {
+        rows: (T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never)[];
+        data: (T["$inferSelect"] extends infer T_2 ? { [K in keyof T_2]: Date extends T_2[K] ? string | Exclude<T_2[K], T_2[K] & Date> : T_2[K]; } : never)[];
+        error: EntityError;
+        isError: true;
+        isPending: false;
+        isLoading: false;
+        isLoadingError: false;
+        isRefetchError: true;
+        isSuccess: false;
+        isPlaceholderData: false;
+        status: "error";
+        dataUpdatedAt: number;
+        errorUpdatedAt: number;
+        failureCount: number;
+        failureReason: EntityError | null;
+        errorUpdateCount: number;
+        isFetched: boolean;
+        isFetchedAfterMount: boolean;
+        isFetching: boolean;
+        isInitialLoading: boolean;
+        isPaused: boolean;
+        isRefetching: boolean;
+        isStale: boolean;
+        isEnabled: boolean;
+        refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<(T["$inferSelect"] extends infer T_3 ? { [K in keyof T_3]: Date extends T_3[K] ? string | Exclude<T_3[K], T_3[K] & Date> : T_3[K]; } : never)[], EntityError>>;
+        fetchStatus: import("@tanstack/react-query").FetchStatus;
+    } | {
+        rows: (T["$inferSelect"] extends infer T_3 ? { [K in keyof T_3]: Date extends T_3[K] ? string | Exclude<T_3[K], T_3[K] & Date> : T_3[K]; } : never)[];
+        data: (T["$inferSelect"] extends infer T_4 ? { [K in keyof T_4]: Date extends T_4[K] ? string | Exclude<T_4[K], T_4[K] & Date> : T_4[K]; } : never)[];
+        error: null;
+        isError: false;
+        isPending: false;
+        isLoading: false;
+        isLoadingError: false;
+        isRefetchError: false;
+        isSuccess: true;
+        isPlaceholderData: false;
+        status: "success";
+        dataUpdatedAt: number;
+        errorUpdatedAt: number;
+        failureCount: number;
+        failureReason: EntityError | null;
+        errorUpdateCount: number;
+        isFetched: boolean;
+        isFetchedAfterMount: boolean;
+        isFetching: boolean;
+        isInitialLoading: boolean;
+        isPaused: boolean;
+        isRefetching: boolean;
+        isStale: boolean;
+        isEnabled: boolean;
+        refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<(T["$inferSelect"] extends infer T_5 ? { [K in keyof T_5]: Date extends T_5[K] ? string | Exclude<T_5[K], T_5[K] & Date> : T_5[K]; } : never)[], EntityError>>;
+        fetchStatus: import("@tanstack/react-query").FetchStatus;
+    } | {
+        rows: (T["$inferSelect"] extends infer T_5 ? { [K in keyof T_5]: Date extends T_5[K] ? string | Exclude<T_5[K], T_5[K] & Date> : T_5[K]; } : never)[];
+        data: undefined;
+        error: EntityError;
+        isError: true;
+        isPending: false;
+        isLoading: false;
+        isLoadingError: true;
+        isRefetchError: false;
+        isSuccess: false;
+        isPlaceholderData: false;
+        status: "error";
+        dataUpdatedAt: number;
+        errorUpdatedAt: number;
+        failureCount: number;
+        failureReason: EntityError | null;
+        errorUpdateCount: number;
+        isFetched: boolean;
+        isFetchedAfterMount: boolean;
+        isFetching: boolean;
+        isInitialLoading: boolean;
+        isPaused: boolean;
+        isRefetching: boolean;
+        isStale: boolean;
+        isEnabled: boolean;
+        refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<(T["$inferSelect"] extends infer T_6 ? { [K in keyof T_6]: Date extends T_6[K] ? string | Exclude<T_6[K], T_6[K] & Date> : T_6[K]; } : never)[], EntityError>>;
+        fetchStatus: import("@tanstack/react-query").FetchStatus;
+    } | {
+        rows: (T["$inferSelect"] extends infer T_6 ? { [K in keyof T_6]: Date extends T_6[K] ? string | Exclude<T_6[K], T_6[K] & Date> : T_6[K]; } : never)[];
+        data: undefined;
+        error: null;
+        isError: false;
+        isPending: true;
+        isLoading: true;
+        isLoadingError: false;
+        isRefetchError: false;
+        isSuccess: false;
+        isPlaceholderData: false;
+        status: "pending";
+        dataUpdatedAt: number;
+        errorUpdatedAt: number;
+        failureCount: number;
+        failureReason: EntityError | null;
+        errorUpdateCount: number;
+        isFetched: boolean;
+        isFetchedAfterMount: boolean;
+        isFetching: boolean;
+        isInitialLoading: boolean;
+        isPaused: boolean;
+        isRefetching: boolean;
+        isStale: boolean;
+        isEnabled: boolean;
+        refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<(T["$inferSelect"] extends infer T_7 ? { [K in keyof T_7]: Date extends T_7[K] ? string | Exclude<T_7[K], T_7[K] & Date> : T_7[K]; } : never)[], EntityError>>;
+        fetchStatus: import("@tanstack/react-query").FetchStatus;
+    } | {
+        rows: (T["$inferSelect"] extends infer T_7 ? { [K in keyof T_7]: Date extends T_7[K] ? string | Exclude<T_7[K], T_7[K] & Date> : T_7[K]; } : never)[];
+        data: undefined;
+        error: null;
+        isError: false;
+        isPending: true;
+        isLoadingError: false;
+        isRefetchError: false;
+        isSuccess: false;
+        isPlaceholderData: false;
+        status: "pending";
+        dataUpdatedAt: number;
+        errorUpdatedAt: number;
+        failureCount: number;
+        failureReason: EntityError | null;
+        errorUpdateCount: number;
+        isFetched: boolean;
+        isFetchedAfterMount: boolean;
+        isFetching: boolean;
+        isLoading: boolean;
+        isInitialLoading: boolean;
+        isPaused: boolean;
+        isRefetching: boolean;
+        isStale: boolean;
+        isEnabled: boolean;
+        refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<(T["$inferSelect"] extends infer T_8 ? { [K in keyof T_8]: Date extends T_8[K] ? string | Exclude<T_8[K], T_8[K] & Date> : T_8[K]; } : never)[], EntityError>>;
+        fetchStatus: import("@tanstack/react-query").FetchStatus;
+    } | {
+        rows: (T["$inferSelect"] extends infer T_8 ? { [K in keyof T_8]: Date extends T_8[K] ? string | Exclude<T_8[K], T_8[K] & Date> : T_8[K]; } : never)[];
+        data: (T["$inferSelect"] extends infer T_9 ? { [K in keyof T_9]: Date extends T_9[K] ? string | Exclude<T_9[K], T_9[K] & Date> : T_9[K]; } : never)[];
+        isError: false;
+        error: null;
+        isPending: false;
+        isLoading: false;
+        isLoadingError: false;
+        isRefetchError: false;
+        isSuccess: true;
+        isPlaceholderData: true;
+        status: "success";
+        dataUpdatedAt: number;
+        errorUpdatedAt: number;
+        failureCount: number;
+        failureReason: EntityError | null;
+        errorUpdateCount: number;
+        isFetched: boolean;
+        isFetchedAfterMount: boolean;
+        isFetching: boolean;
+        isInitialLoading: boolean;
+        isPaused: boolean;
+        isRefetching: boolean;
+        isStale: boolean;
+        isEnabled: boolean;
+        refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<(T["$inferSelect"] extends infer T_10 ? { [K in keyof T_10]: Date extends T_10[K] ? string | Exclude<T_10[K], T_10[K] & Date> : T_10[K]; } : never)[], EntityError>>;
+        fetchStatus: import("@tanstack/react-query").FetchStatus;
+    };
     /** One row; `null` waits (nothing open yet). */
     useGet: (id: string | null) => import("@tanstack/react-query").UseQueryResult<T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never, EntityError>;
     useCreate: () => import("@tanstack/react-query").UseMutationResult<T["$inferSelect"] extends infer T_1 ? { [K in keyof T_1]: Date extends T_1[K] ? string | Exclude<T_1[K], T_1[K] & Date> : T_1[K]; } : never, EntityError, NewRow<T>, unknown>;

package/dist/client.js

@@ -17,6 +17,8 @@ export { InvocationError } from "@shubh90/app-runtime/invoke";
 export function createApp() {
     return { table: tableClient, contracts: createInvoker() };
 }
+/** Every list's rows before its first answer: one array, so they never change identity while pending. */
+const NO_ROWS = [];
 /** One entity table's rows: plain calls, and TanStack Query hooks over them. */
 function tableClient(entity) {
     const base = `${ENTITIES_PATH}/${getTableName(entity)}`;
@@ -58,8 +60,19 @@ function tableClient(entity) {
         create,
         update,
         delete: remove,
-        /** The rows, cached per options; refetched after any write to this table. */
-        useList: (options = {}) => useQuery({ queryKey: keys.list(options), queryFn: () => list(options) }),
+        /**
+         * The query (`isPending`, `isError`, `error`, `refetch`) and its `rows`,
+         * cached per options and refetched after any write to this table. `rows`
+         * is never undefined: empty until the first answer, and the same array
+         * until the rows change, so it can sit in a hook's dependencies.
+         */
+        useList: (options = {}) => {
+            const query = useQuery({ queryKey: keys.list(options), queryFn: () => list(options) });
+            const { data: rows = NO_ROWS } = query;
+            // A spread reads every field, so the page re-renders on any of them (isFetching
+            // too); a list page shows those states anyway, and it keeps the result plain.
+            return { ...query, rows };
+        },
         /** One row; `null` waits (nothing open yet). */
         useGet: (id) => useQuery({
             queryKey: keys.get(id),

package/dist/platform.js

@@ -1,5 +1,5 @@
 // The platform contract a page and the global middleware need: framing by
-// Plaza's App pane, the server-function door, analytics and error policies,
+// the platform's App pane, the server-function door, analytics and error policies,
 // and the pane bridge. Behaviour lives in @shubh90/app-runtime.
 export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS } from "@shubh90/app-runtime/platform";
 export { MiiPaneBridge } from "@shubh90/app-runtime/react";

package/dist/server/entities.js

@@ -37,11 +37,11 @@ export function createEntitiesHandler(options) {
         .map((entity) => [getTableName(entity), tableRules(entity)]));
     return async (request) => {
         const url = new URL(request.url);
-        // Every org app shares one site (*.miis.run): only this app's pages may use it.
+        // Every org app shares one site (*.<domain>): only this app's pages may use it.
         if (!isSameOrigin(request, url)) {
             return refuse(403, "cross_site", "Only this app's own pages can use its data.");
         }
-        // No Plaza to sign in with: only a bare local dev server serves (as the
+        // No platform to sign in with: only a bare local dev server serves (as the
         // local developer). A deployment or a sandbox missing its sign-in config serves nothing.
         const { configured, local } = env();
         if (!configured && !local) {

package/dist/server/env.d.ts

@@ -2,10 +2,10 @@
 export declare function env(): {
     databaseUrl: string | undefined;
     unpooledDatabaseUrl: string | undefined;
-    /** Sign-in needs Plaza, this app's id in it, and a database for sessions. */
+    /** Sign-in needs the platform, this app's id in it, and a database for sessions. */
     configured: boolean;
     /**
-     * A bare local dev server: no Plaza and no app id at all (the platform
+     * A bare local dev server: no platform and no app id at all (the platform
      * gives every sandbox and deployment its MII_APP_ID), and not production.
      */
     local: boolean;

package/dist/server/env.js

@@ -13,10 +13,10 @@ const serverEnv = z
     .transform((env) => ({
     databaseUrl: env.DATABASE_URL,
     unpooledDatabaseUrl: env.DATABASE_URL_UNPOOLED,
-    /** Sign-in needs Plaza, this app's id in it, and a database for sessions. */
+    /** Sign-in needs the platform, this app's id in it, and a database for sessions. */
     configured: Boolean(env.MII_PLAZA_URL && env.MII_APP_ID && env.DATABASE_URL),
     /**
-     * A bare local dev server: no Plaza and no app id at all (the platform
+     * A bare local dev server: no platform and no app id at all (the platform
      * gives every sandbox and deployment its MII_APP_ID), and not production.
      */
     local: !env.MII_PLAZA_URL && !env.MII_APP_ID && env.NODE_ENV !== "production"

package/dist/server/index.d.ts

@@ -12,7 +12,7 @@ export declare function createLightServer<S extends Record<string, unknown>, C e
     session: (request: Request) => Promise<import("./session.js").SessionState>;
     /** Whether sign-in is configured (a bare local dev server has none). */
     configured: () => boolean;
-    /** Email and password, checked by Plaza; the session to set as a cookie, or why not. */
+    /** Email and password, checked by the platform; the session to set as a cookie, or why not. */
     signIn: (email: string, password: string) => Promise<import("./session.js").SignIn>;
     /** The app's database, typed by its schema: `light.db.select().from(companies)`. */
     readonly db: PostgresJsDatabase<S>;
@@ -22,7 +22,7 @@ export declare function createLightServer<S extends Record<string, unknown>, C e
     image: (request: Request) => Promise<Response>;
     /** Server-side starts and reads of the app's contracts. */
     invoke: import("@shubh90/app-runtime/invoke/server").MiiInvoke<C>;
-    /** `/api/mii/invoke/*`: the contract buttons, forwarded to Plaza as the person. */
+    /** `/api/mii/invoke/*`: the contract buttons, forwarded to the platform as the person. */
     invokeRoute: (request: Request) => Promise<Response>;
     /** `/api/mii/chat/*`: the chat bubble's calls to the org's agents. */
     chatRoute: (request: Request) => Promise<Response>;

package/dist/server/index.js

@@ -1,5 +1,5 @@
 // The app's server half, bound once in `src/server/light.ts`: its database,
-// its door (sign-in through Plaza), and the routes the SDK serves (entities,
+// its door (sign-in through the platform), and the routes the SDK serves (entities,
 // images, contracts, chat). Server-only.
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
@@ -35,7 +35,7 @@ export function createLightServer(options) {
         session,
         /** Whether sign-in is configured (a bare local dev server has none). */
         configured: () => env().configured,
-        /** Email and password, checked by Plaza; the session to set as a cookie, or why not. */
+        /** Email and password, checked by the platform; the session to set as a cookie, or why not. */
         signIn: (email, password) => signIn(auth, email, password),
         /** The app's database, typed by its schema: `light.db.select().from(companies)`. */
         get db() {
@@ -47,13 +47,13 @@ export function createLightServer(options) {
         image: createImageHandler({ db, session }),
         /** Server-side starts and reads of the app's contracts. */
         invoke,
-        /** `/api/mii/invoke/*`: the contract buttons, forwarded to Plaza as the person. */
+        /** `/api/mii/invoke/*`: the contract buttons, forwarded to the platform as the person. */
         invokeRoute: needsSignIn(invoke.handler),
         /** `/api/mii/chat/*`: the chat bubble's calls to the org's agents. */
         chatRoute: needsSignIn(chat)
     };
 }
-/** A route that forwards to Plaza as the person: nothing to forward without sign-in. */
+/** A route that forwards to the platform as the person: nothing to forward without sign-in. */
 function needsSignIn(handler) {
     return (request) => env().configured
         ? handler(request)

package/dist/server/session.d.ts

@@ -14,5 +14,5 @@ export type SignIn = {
     ok: false;
     message: string;
 };
-/** The login form's whole job: Plaza checks the password, the app starts a session. */
+/** The login form's whole job: the platform checks the password, the app starts a session. */
 export declare function signIn(auth: MiiAuthCore, email: string, password: string): Promise<SignIn>;

package/dist/server/session.js

@@ -1,10 +1,10 @@
-// Who is asking, as the app's door sees it, and signing in through Plaza.
+// Who is asking, as the app's door sees it, and signing in through the platform.
 import { signInWithPlaza } from "@shubh90/app-runtime/auth/core";
 import { readCookie } from "@shubh90/app-runtime/chat/server";
 import { env } from "./env.js";
 /** The session a request's cookie names, and whether the app is members-only. */
 export async function readSession(auth, request) {
-    // No Plaza to sign in with: a bare local dev server has no door; any other
+    // No platform to sign in with: a bare local dev server has no door; any other
     // server without its sign-in config keeps the door shut.
     const { configured, local } = env();
     if (!configured)
@@ -13,14 +13,14 @@ export async function readSession(auth, request) {
     let found = null;
     if (token !== null)
         found = await auth.resolveSession(token);
-    // Plaza unreachable on a cold start throws: an error page, not a door that guesses.
+    // The platform unreachable on a cold start throws: an error page, not a door that guesses.
     const mode = await auth.getAuthMode();
     if (found === null)
         return { user: null, mode };
     const { id, name, email, avatarUrl, role } = found;
     return { user: { id, name, email, avatarUrl, role }, mode };
 }
-/** The login form's whole job: Plaza checks the password, the app starts a session. */
+/** The login form's whole job: the platform checks the password, the app starts a session. */
 export async function signIn(auth, email, password) {
     if (!env().configured)
         return { ok: false, message: "Sign-in is not configured." };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "The Light SDK every v2 org app depends on: entities (Drizzle tables with a typed client), sign-in, contracts and in-app chat.",
   "license": "UNLICENSED",
   "type": "module",
@@ -63,6 +63,7 @@
     "@tanstack/react-query": "^5.104.0",
     "@types/node": "^22.20.4",
     "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "drizzle-orm": "^0.45.3",
     "eslint": "^10.11.0",
     "postgres": "^3.4.9",