@better-apps/comments 0.0.0-stage → 0.0.0

package/dist/client.js

@@ -0,0 +1,598 @@
+import { createStore } from "better-apps/client";
+import { textFormat } from "./formats.js";
+import { ulid } from "./ulid.js";
+export { textFormat } from "./formats.js";
+export { isUlid, ulid } from "./ulid.js";
+/** Keys a list by its subject and options. */
+export function listKey(subject, options = {}) {
+    return JSON.stringify([subject.subjectType, subject.subjectId, options.status ?? null, options.order ?? "activity"]);
+}
+/** Keys a subject's counts. */
+export function countKey(subjectType, subjectId) {
+    return JSON.stringify([subjectType, subjectId]);
+}
+const toDate = (value) => (typeof value === "string" ? new Date(value) : value);
+function reviveThread(thread) {
+    const row = thread;
+    return {
+        ...row,
+        createdAt: toDate(row.createdAt),
+        lastActivityAt: toDate(row.lastActivityAt),
+        resolvedAt: toDate(row.resolvedAt ?? null)
+    };
+}
+function reviveComment(comment) {
+    const row = comment;
+    return {
+        ...row,
+        createdAt: toDate(row.createdAt),
+        editedAt: toDate(row.editedAt ?? null),
+        deletedAt: toDate(row.deletedAt ?? null)
+    };
+}
+const empty = {
+    threads: {},
+    comments: {},
+    threadComments: {},
+    lists: {},
+    counts: {},
+    users: {},
+    pending: {}
+};
+function without(record, ...keys) {
+    const copy = { ...record };
+    for (const key of keys) {
+        delete copy[key];
+    }
+    return copy;
+}
+const remembered = 1000;
+const clients = new WeakMap();
+/**
+ * Creates the comments store for a Better Apps client. Pass `typeof app` as the client's type to get the app's subject
+ * types, anchors, formats and additional fields. Each Better Apps client has one store, so calling this again with the
+ * same client, as `useComments` does, returns the store already made, with whatever a server render hydrated into it.
+ *
+ * The store holds what the signed-in person could see. When someone else signs in without a page load, call `reset()`
+ * or create a new Better Apps client, so they never see the previous person's threads.
+ */
+export function createCommentsClient(client) {
+    let comments = clients.get(client);
+    if (!comments) {
+        comments = createCommentsClientFor(client.$call);
+        clients.set(client, comments);
+    }
+    return comments;
+}
+function createCommentsClientFor(call) {
+    const store = createStore(empty);
+    // reset() cancels calls still under way, so one waiting on its headers never goes out as the next person.
+    let calls = new AbortController();
+    const run = (action, input) => call("comments", action, input, { signal: calls.signal });
+    const applied = [];
+    const resetListeners = new Set();
+    const update = (change) => store.setState(change);
+    // reset() starts a new generation. Answers to requests made before it belong to the previous person, so an
+    // operation applies its changes only while its generation is current.
+    let generation = 0;
+    const scoped = () => {
+        const started = generation;
+        return (change) => {
+            if (started === generation) {
+                update(change);
+            }
+        };
+    };
+    const mergeUsers = (state, users) => users && Object.keys(users).length > 0 ? { ...state, users: { ...state.users, ...users } } : state;
+    /**
+     * Keeps a thread's place in its subject's lists: a new thread goes on top, a new comment moves its thread to the top
+     * of lists by activity, and a thread leaves lists whose status it no longer has. A thread a list hasn't loaded is
+     * only added when it's new or just had activity, since its place is otherwise unknown.
+     */
+    const placeThread = (state, thread, change) => {
+        const lists = { ...state.lists };
+        for (const [key, list] of Object.entries(state.lists)) {
+            if (list.subjectType !== thread.subjectType || list.subjectId !== thread.subjectId) {
+                continue;
+            }
+            const present = list.ids.includes(thread.id);
+            const rest = list.ids.filter((id) => id !== thread.id);
+            const toTop = change.isNew === true || (change.bump === true && list.order === "activity");
+            if (list.status !== null && list.status !== thread.status) {
+                lists[key] = present ? { ...list, ids: rest } : list;
+            }
+            else if (toTop) {
+                lists[key] = { ...list, ids: [thread.id, ...rest] };
+            }
+        }
+        return { ...state, lists };
+    };
+    const countChange = (state, thread, total, open) => {
+        const key = countKey(thread.subjectType, thread.subjectId);
+        const counts = state.counts[key];
+        // Counts still loading arrive from the server with the change in them, or without it, and replace these anyway.
+        if (counts?.state !== "ready") {
+            return state;
+        }
+        return {
+            ...state,
+            counts: { ...state.counts, [key]: { ...counts, total: counts.total + total, open: counts.open + open } }
+        };
+    };
+    const putThread = (state, thread) => ({
+        ...state,
+        threads: { ...state.threads, [thread.id]: thread }
+    });
+    const putComment = (state, comment, append) => {
+        const loaded = state.threadComments[comment.threadId];
+        const threadComments = append && loaded && !loaded.ids.includes(comment.id)
+            ? { ...state.threadComments, [comment.threadId]: { ...loaded, ids: [...loaded.ids, comment.id] } }
+            : state.threadComments;
+        return { ...state, comments: { ...state.comments, [comment.id]: comment }, threadComments };
+    };
+    const removeThread = (state, threadId) => {
+        const thread = state.threads[threadId];
+        const commentIds = state.threadComments[threadId]?.ids ?? [];
+        let next = {
+            ...state,
+            threads: without(state.threads, threadId),
+            comments: without(state.comments, ...commentIds),
+            threadComments: without(state.threadComments, threadId),
+            lists: Object.fromEntries(Object.entries(state.lists).map(([key, list]) => [
+                key,
+                { ...list, ids: list.ids.filter((id) => id !== threadId) }
+            ]))
+        };
+        if (thread) {
+            next = countChange(next, thread, -1, thread.status === "open" ? -1 : 0);
+        }
+        return next;
+    };
+    /** Applies a change now and returns a function that undoes it, for when the server refuses the write. */
+    const optimistic = (change, ids) => {
+        const before = store.getSnapshot();
+        const apply = scoped();
+        apply((state) => {
+            const next = change(state);
+            return { ...next, pending: { ...next.pending, ...Object.fromEntries(ids.map((id) => [id, true])) } };
+        });
+        const settle = () => apply((state) => ({ ...state, pending: without(state.pending, ...ids) }));
+        const undo = () => apply((state) => ({
+            ...before,
+            // Keep what was loaded meanwhile; only the optimistic change is rolled back.
+            users: state.users,
+            pending: without(state.pending, ...ids)
+        }));
+        return { settle, undo };
+    };
+    async function write(action, input, change, ids, confirm) {
+        const apply = scoped();
+        const { settle, undo } = optimistic(change, ids);
+        let output;
+        try {
+            output = (await run(action, input));
+        }
+        catch (error) {
+            undo();
+            throw error;
+        }
+        apply((state) => confirm(state, output));
+        settle();
+        return output;
+    }
+    const existing = (threadId) => {
+        const thread = store.getSnapshot().threads[threadId];
+        if (!thread) {
+            throw new Error(`Load thread ${threadId} before changing it.`);
+        }
+        return thread;
+    };
+    return {
+        store,
+        /** Loads the first page of a subject's threads. */
+        async loadThreads(subject, options = {}) {
+            const key = listKey(subject, options);
+            const blank = {
+                subjectType: subject.subjectType,
+                subjectId: subject.subjectId,
+                status: options.status ?? null,
+                order: options.order ?? "activity",
+                ids: [],
+                cursor: null,
+                state: "loading",
+                error: null
+            };
+            update((state) => ({
+                ...state,
+                lists: { ...state.lists, [key]: { ...(state.lists[key] ?? blank), state: "loading", error: null } }
+            }));
+            await loadPage(key, { ...subject, ...options }, false);
+        },
+        /** Loads the next page of a list loaded with `loadThreads`. */
+        async loadMoreThreads(subject, options = {}) {
+            const key = listKey(subject, options);
+            const list = store.getSnapshot().lists[key];
+            if (!list?.cursor || list.state === "loading") {
+                return;
+            }
+            update((state) => ({ ...state, lists: { ...state.lists, [key]: { ...list, state: "loading" } } }));
+            await loadPage(key, { ...subject, ...options, cursor: list.cursor }, true);
+        },
+        /** Loads a thread and the first page of its comments. */
+        async loadThread(threadId) {
+            await loadComments({ threadId }, false);
+        },
+        /** Loads the next page of a thread's comments. */
+        async loadMoreComments(threadId) {
+            const loaded = store.getSnapshot().threadComments[threadId];
+            if (loaded?.cursor && loaded.state !== "loading") {
+                await loadComments({ threadId, cursor: loaded.cursor }, true);
+            }
+        },
+        /** Loads open and total counts for many subjects, 50 per call. */
+        async loadCounts(subjectType, subjectIds) {
+            const apply = scoped();
+            const unique = [...new Set(subjectIds)];
+            const pages = [];
+            for (let start = 0; start < unique.length; start += 50) {
+                pages.push(unique.slice(start, start + 50));
+            }
+            // Counts not loaded yet are marked as loading, so a reset meanwhile shows they're missing again.
+            const placeholders = (state, loadState) => Object.fromEntries(unique.flatMap((subjectId) => {
+                const key = countKey(subjectType, subjectId);
+                const current = state[key];
+                return current?.state === "ready" ? [] : [[key, { open: 0, total: 0, state: loadState }]];
+            }));
+            apply((state) => ({ ...state, counts: { ...state.counts, ...placeholders(state.counts, "loading") } }));
+            try {
+                await Promise.all(pages.map(async (page) => {
+                    const input = { subjectType, subjectIds: page };
+                    const counts = (await run("countThreads", input));
+                    apply((state) => ({
+                        ...state,
+                        counts: {
+                            ...state.counts,
+                            ...Object.fromEntries(page.map((subjectId) => [
+                                countKey(subjectType, subjectId),
+                                { ...(counts[subjectId] ?? { open: 0, total: 0 }), state: "ready" }
+                            ]))
+                        }
+                    }));
+                }));
+            }
+            catch (error) {
+                apply((state) => ({ ...state, counts: { ...state.counts, ...placeholders(state.counts, "error") } }));
+                throw error;
+            }
+        },
+        /** Starts a thread. It shows at once under its final id, and is rolled back if the server refuses it. */
+        async createThread(input) {
+            const id = input.id ?? ulid();
+            const commentId = input.commentId ?? ulid();
+            const now = new Date();
+            const anchor = input.anchor ?? null;
+            const thread = {
+                id,
+                orgId: "",
+                subjectType: input.subjectType,
+                subjectId: input.subjectId,
+                visibility: input.visibility ?? "default",
+                anchorKind: anchor?.kind ?? null,
+                anchor: anchor?.value ?? null,
+                anchorVersion: anchor?.version ?? null,
+                status: "open",
+                resolvedAt: null,
+                resolvedBy: null,
+                createdBy: "",
+                createdAt: now,
+                lastActivityAt: now,
+                commentCount: 1,
+                metadata: input.metadata ?? null,
+                ...input.fields
+            };
+            const comment = draftComment(commentId, thread, input, now, input.commentFields);
+            const output = await write("createThread", { ...input, id, commentId }, (state) => {
+                let next = putComment(putThread(state, thread), comment, false);
+                next = {
+                    ...next,
+                    threadComments: {
+                        ...next.threadComments,
+                        [id]: { ids: [commentId], cursor: null, state: "ready", error: null }
+                    }
+                };
+                return countChange(placeThread(next, thread, { isNew: true }), thread, 1, 1);
+            }, [id, commentId], (state, result) => putComment(putThread(state, reviveThread(result.thread)), reviveComment(result.comment), false));
+            return {
+                thread: reviveThread(output.thread),
+                comment: reviveComment(output.comment),
+                droppedMentions: output.droppedMentions
+            };
+        },
+        /** Replies to a thread, reopening it if it was resolved. */
+        async reply(input) {
+            const thread = existing(input.threadId);
+            const id = input.id ?? ulid();
+            const now = new Date();
+            const comment = draftComment(id, thread, input, now, input.fields);
+            const bumped = {
+                ...thread,
+                status: "open",
+                resolvedAt: null,
+                resolvedBy: null,
+                commentCount: thread.commentCount + 1,
+                lastActivityAt: now
+            };
+            const output = await write("reply", { ...input, id }, (state) => {
+                const reopened = thread.status === "resolved" ? 1 : 0;
+                return countChange(placeThread(putComment(putThread(state, bumped), comment, true), bumped, { bump: true }), bumped, 0, reopened);
+            }, [id], (state, result) => putComment(putThread(state, reviveThread(result.thread)), reviveComment(result.comment), true));
+            return {
+                thread: reviveThread(output.thread),
+                comment: reviveComment(output.comment),
+                droppedMentions: output.droppedMentions
+            };
+        },
+        async editComment(input) {
+            const comment = store.getSnapshot().comments[input.commentId];
+            const format = input.format ?? "text";
+            const edited = comment && {
+                ...comment,
+                format,
+                body: input.body,
+                bodyText: format === "text" ? textFormat.toText(String(input.body)) : comment.bodyText,
+                editedAt: new Date()
+            };
+            const output = await write("editComment", input, (state) => (edited ? putComment(state, edited, false) : state), [input.commentId], (state, result) => putComment(state, reviveComment(result.comment), false));
+            return { comment: reviveComment(output.comment), droppedMentions: output.droppedMentions };
+        },
+        async deleteComment(input) {
+            const comment = store.getSnapshot().comments[input.commentId];
+            const thread = comment && store.getSnapshot().threads[comment.threadId];
+            const output = await write("deleteComment", input, (state) => {
+                if (!comment || !thread || comment.deletedAt) {
+                    return state;
+                }
+                const deleted = { ...comment, body: null, bodyText: "", deletedAt: new Date() };
+                return putThread(putComment(state, deleted, false), { ...thread, commentCount: thread.commentCount - 1 });
+            }, [input.commentId], (state, result) => {
+                const deleted = reviveComment(result.comment);
+                return result.threadDeleted ? removeThread(state, deleted.threadId) : putComment(state, deleted, false);
+            });
+            return { comment: reviveComment(output.comment), threadDeleted: output.threadDeleted };
+        },
+        resolveThread: (input) => setStatus("resolveThread", input, "resolved"),
+        reopenThread: (input) => setStatus("reopenThread", input, "open"),
+        async updateThread(input) {
+            const thread = existing(input.threadId);
+            const changed = {
+                ...thread,
+                ...input.fields,
+                ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+                ...(input.visibility === undefined ? {} : { visibility: input.visibility })
+            };
+            return confirmThread("updateThread", input, changed);
+        },
+        async updateAnchor(input) {
+            const thread = existing(input.threadId);
+            const changed = {
+                ...thread,
+                anchorKind: input.anchor?.kind ?? null,
+                anchor: input.anchor?.value ?? null,
+                anchorVersion: input.anchor?.version ?? null
+            };
+            return confirmThread("updateAnchor", input, changed);
+        },
+        async deleteThread(input) {
+            return write("deleteThread", input, (state) => removeThread(state, input.threadId), [input.threadId], (state) => state);
+        },
+        /**
+         * Suggests users to mention in a thread, or on a subject before its thread exists. A search that a `reset()`
+         * overtakes suggests nobody, since it ran as the previous person.
+         */
+        async suggestMentions(input) {
+            const started = generation;
+            try {
+                const users = (await run("suggestMentions", input));
+                return started === generation ? users : [];
+            }
+            catch (error) {
+                if (started !== generation) {
+                    return [];
+                }
+                throw error;
+            }
+        },
+        /**
+         * Applies a live update from `toClientEvent`. Events it has already applied, and comments it already has, are
+         * ignored, so an event that arrives before the server's own answer doesn't duplicate a comment.
+         */
+        applyEvent(event) {
+            if (applied.includes(event.id)) {
+                return;
+            }
+            applied.push(event.id);
+            applied.splice(0, Math.max(0, applied.length - remembered));
+            const thread = reviveThread(event.thread);
+            update((state) => {
+                if (event.type === "thread.deleted") {
+                    return removeThread(state, thread.id);
+                }
+                const known = state.threads[thread.id];
+                let next = putThread(state, thread);
+                if ("comment" in event) {
+                    const comment = reviveComment(event.comment);
+                    next = putComment(next, comment, true);
+                }
+                const isNew = event.type === "thread.created" && !known;
+                if (isNew) {
+                    next = countChange(next, thread, 1, thread.status === "open" ? 1 : 0);
+                }
+                else if (known && known.status !== thread.status) {
+                    next = countChange(next, thread, 0, thread.status === "open" ? 1 : -1);
+                }
+                return placeThread(next, thread, { isNew, bump: event.type === "comment.created" });
+            });
+        },
+        /** The store's state as JSON can carry it, to send a server render's loads to the browser. */
+        dehydrate() {
+            // Through JSON on purpose, so dates become the strings a server render sends. Only loaded counts go, since the
+            // browser loads counts it doesn't have and would keep ones marked loading or failed.
+            const state = store.getSnapshot();
+            const counts = Object.fromEntries(Object.entries(state.counts).filter(([, count]) => count.state === "ready"));
+            const json = JSON.stringify({ ...state, counts, pending: {} });
+            return JSON.parse(json);
+        },
+        /**
+         * Empties the store, such as when the signed-in person changes without a page load. Lists and threads that are on
+         * screen load again for the new person. Calls still under way are cancelled and reject with an `ABORTED` error.
+         */
+        reset() {
+            generation += 1;
+            calls.abort();
+            calls = new AbortController();
+            applied.length = 0;
+            store.setState(() => empty);
+            for (const listener of Array.from(resetListeners)) {
+                listener();
+            }
+        },
+        /**
+         * Calls `listener` after each `reset()`, such as to clear state kept outside the store that the previous person could
+         * see. Returns a function that stops it.
+         */
+        onReset(listener) {
+            resetListeners.add(listener);
+            return () => {
+                resetListeners.delete(listener);
+            };
+        },
+        /** Merges a snapshot from `dehydrate`, such as one a server render loaded. */
+        hydrate(snapshot) {
+            update((state) => ({
+                threads: {
+                    ...state.threads,
+                    ...Object.fromEntries(Object.entries(snapshot.threads).map(([id, thread]) => [id, reviveThread(thread)]))
+                },
+                comments: {
+                    ...state.comments,
+                    ...Object.fromEntries(Object.entries(snapshot.comments).map(([id, comment]) => [id, reviveComment(comment)]))
+                },
+                threadComments: { ...state.threadComments, ...snapshot.threadComments },
+                lists: { ...state.lists, ...snapshot.lists },
+                counts: {
+                    ...state.counts,
+                    ...Object.fromEntries(Object.entries(snapshot.counts).filter(([, count]) => count.state === "ready"))
+                },
+                users: { ...state.users, ...snapshot.users },
+                pending: state.pending
+            }));
+        }
+    };
+    function draftComment(id, thread, input, now, fields) {
+        const format = input.format ?? "text";
+        return {
+            id,
+            threadId: thread.id,
+            orgId: thread.orgId,
+            authorType: "user",
+            authorId: "",
+            authorName: null,
+            format,
+            body: input.body,
+            bodyText: format === "text" ? textFormat.toText(String(input.body)) : "",
+            createdAt: now,
+            editedAt: null,
+            deletedAt: null,
+            metadata: null,
+            ...fields
+        };
+    }
+    async function loadPage(key, input, append) {
+        const apply = scoped();
+        try {
+            const page = (await run("listThreads", input));
+            const threads = page.threads.map((thread) => reviveThread(thread));
+            apply((state) => {
+                const list = state.lists[key];
+                const ids = threads.map((thread) => thread.id);
+                // Threads that moved up through an event while paging are already listed, so they aren't repeated.
+                const merged = append ? [...list.ids, ...ids.filter((id) => !list.ids.includes(id))] : ids;
+                return mergeUsers({
+                    ...state,
+                    threads: { ...state.threads, ...Object.fromEntries(threads.map((thread) => [thread.id, thread])) },
+                    lists: { ...state.lists, [key]: { ...list, ids: merged, cursor: page.cursor, state: "ready", error: null } }
+                }, page.users);
+            });
+        }
+        catch (error) {
+            apply((state) => ({
+                ...state,
+                lists: { ...state.lists, [key]: { ...state.lists[key], state: "error", error: error } }
+            }));
+            throw error;
+        }
+    }
+    async function loadComments(input, append) {
+        const { threadId } = input;
+        const apply = scoped();
+        apply((state) => ({
+            ...state,
+            threadComments: {
+                ...state.threadComments,
+                [threadId]: { ...(state.threadComments[threadId] ?? { ids: [], cursor: null }), state: "loading", error: null }
+            }
+        }));
+        try {
+            const page = (await run("getThread", input));
+            const comments = page.comments.map((comment) => reviveComment(comment));
+            apply((state) => {
+                const loaded = state.threadComments[threadId];
+                const ids = comments.map((comment) => comment.id);
+                return mergeUsers({
+                    ...putThread(state, reviveThread(page.thread)),
+                    comments: { ...state.comments, ...Object.fromEntries(comments.map((comment) => [comment.id, comment])) },
+                    threadComments: {
+                        ...state.threadComments,
+                        [threadId]: {
+                            ids: append ? [...loaded.ids, ...ids.filter((id) => !loaded.ids.includes(id))] : ids,
+                            cursor: page.cursor,
+                            state: "ready",
+                            error: null
+                        }
+                    }
+                }, page.users);
+            });
+        }
+        catch (error) {
+            apply((state) => ({
+                ...state,
+                threadComments: {
+                    ...state.threadComments,
+                    [threadId]: { ...state.threadComments[threadId], state: "error", error: error }
+                }
+            }));
+            throw error;
+        }
+    }
+    async function setStatus(action, input, status) {
+        const thread = existing(input.threadId);
+        const changed = {
+            ...thread,
+            status,
+            resolvedAt: status === "resolved" ? new Date() : null,
+            resolvedBy: status === "resolved" ? thread.resolvedBy : null
+        };
+        return confirmThread(action, input, changed);
+    }
+    async function confirmThread(action, input, changed) {
+        const previous = store.getSnapshot().threads[changed.id];
+        const output = await write(action, input, (state) => {
+            let next = putThread(state, changed);
+            if (previous && previous.status !== changed.status) {
+                next = countChange(next, changed, 0, changed.status === "open" ? 1 : -1);
+            }
+            return placeThread(next, changed, {});
+        }, [changed.id], (state, result) => putThread(state, reviveThread(result)));
+        return reviveThread(output);
+    }
+}

package/dist/content.d.ts

@@ -0,0 +1,45 @@
+import type { AnchorKind } from "@better-apps/anchors";
+import type { FieldAttribute, StandardSchemaV1 } from "better-apps";
+import type { BodyFormat } from "./formats.js";
+/** Size and count limits. Queries that pass lists of ids stay under D1's 100 bound parameters. */
+export declare const limits: {
+    readonly bodyBytes: number;
+    readonly anchorBytes: number;
+    readonly metadataBytes: number;
+    readonly mentions: 20;
+    readonly threadsPerPage: 20;
+    readonly maxThreadsPerPage: 50;
+    readonly commentsPerPage: 50;
+    readonly maxCommentsPerPage: 100;
+    readonly subjectsPerCount: 50;
+    readonly suggestions: 10;
+};
+/** The size of a value as JSON, in UTF-8 bytes. */
+export declare function jsonBytes(value: unknown): number;
+/** JSON with object keys sorted, so equal values compare equal however they were built. */
+export declare function stableJson(value: unknown): string;
+/** A comment body after its format checked and sanitized it, with its text and mentions. */
+export interface CheckedContent {
+    format: string;
+    body: unknown;
+    bodyText: string;
+    mentions: string[];
+}
+/** Checks, sanitizes and measures a body in a registered format. */
+export declare function checkContent(formats: ReadonlyMap<string, BodyFormat>, formatName: string | undefined, body: unknown): Promise<CheckedContent>;
+/** A thread's anchor as stored. */
+export interface CheckedAnchor {
+    anchorKind: string | null;
+    anchor: unknown;
+    anchorVersion: string | null;
+}
+/** Checks an anchor against its registered kind. `null` puts the thread on the whole subject. */
+export declare function checkAnchor(anchors: ReadonlyMap<string, AnchorKind>, anchor: {
+    kind: string;
+    value: unknown;
+    version?: string | null | undefined;
+} | null | undefined): Promise<CheckedAnchor>;
+/** Checks metadata against a subject type's schema, when it has one, and its size. */
+export declare function checkMetadata(schema: StandardSchemaV1<unknown, Record<string, unknown>> | undefined, metadata: Record<string, unknown> | null): Promise<Record<string, unknown> | null>;
+/** Checks values for an app's additional fields. Fields it didn't declare are refused. */
+export declare function checkFields(declared: Readonly<Record<string, FieldAttribute>>, values: Readonly<Record<string, unknown>> | undefined): Record<string, unknown>;