@antelopejs/dms 0.11.1 → 0.12.0

package/frontend-vue/layers/dms-core/app/composables/realtime/useUserRealtime.ts

@@ -2,9 +2,11 @@ import {
   createReconnector,
   joinSharedRealtimeConnection,
   recoverFromError,
+  type SharedRealtimeConnectionOptions,
   type StreamRecovery,
 } from "../../build/utils/sharedRealtimeConnection";
 import { HTTP_UNAUTHORIZED } from "../../utils/http-status";
+import { isObject, isString } from "../../utils/type-check";
 
 const REALTIME_CONNECTION_PATH = "/api/realtime/connection";
 const REALTIME_SESSION_PATH = "/api/realtime/session";
@@ -22,9 +24,14 @@ const SESSION_ENDED_EVENT = "session-ended";
 /** Frames held while a session is being opened, every tab's included. */
 const MAX_BUFFERED_FRAMES = 256;
 
+type RealtimeFrameData = Parameters<
+  SharedRealtimeConnectionOptions["onFrame"]
+>[2];
+
 export interface RealtimeEvent {
   topic: string;
   type: string;
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- Backend realtime/broker.ts owns the same arbitrary payload contract; topic-specific schemas cannot narrow this public event interface.
   payload?: Record<string, unknown>;
   actorId?: string;
   ts: number;
@@ -127,40 +134,33 @@ const dispatchToHandlers = (
 
 const isSnapshotEvent = (
   eventName: string,
-  data: unknown,
+  data: RealtimeFrameData,
 ): data is RealtimeSnapshotEvent =>
-  eventName === SNAPSHOT_EVENT &&
-  !!data &&
-  typeof data === "object" &&
-  "topic" in (data as Record<string, unknown>);
-
-const isRealtimeEvent = (data: unknown): data is RealtimeEvent =>
-  !!data &&
-  typeof data === "object" &&
-  typeof (data as Record<string, unknown>).topic === "string" &&
-  typeof (data as Record<string, unknown>).type === "string";
-
-const readMenuTopics = (data: object): string[] => {
-  const { menuTopics } = data as { menuTopics?: unknown };
-  if (!Array.isArray(menuTopics)) return [];
-  return menuTopics.filter(
-    (topic): topic is string => typeof topic === "string",
-  );
-};
+  eventName === SNAPSHOT_EVENT && !!data && isObject(data) && "topic" in data;
+
+const isRealtimeEvent = (data: RealtimeFrameData): data is RealtimeEvent =>
+  !!data && isObject(data) && isString(data.topic) && isString(data.type);
 
 /** Takes the session a greeting names, with the menu topics it announces. */
-const handleHello = (state: UserRealtimeState, data: unknown): void => {
-  if (!data || typeof data !== "object" || !("sessionId" in data)) return;
-  state.sessionId.value = String((data as { sessionId: unknown }).sessionId);
-  state.menuTopics.value = readMenuTopics(data);
-  const { devReloadTopic } = data as { devReloadTopic?: unknown };
-  state.devReloadTopic.value =
-    typeof devReloadTopic === "string" ? devReloadTopic : undefined;
+const handleHello = (
+  state: UserRealtimeState,
+  data: RealtimeFrameData,
+): void => {
+  if (!data || !isObject(data) || !("sessionId" in data)) return;
+  state.sessionId.value = String(data.sessionId);
+  const { menuTopics } = data;
+  state.menuTopics.value = Array.isArray(menuTopics)
+    ? menuTopics.filter((topic): topic is string => isString(topic))
+    : [];
+  const { devReloadTopic } = data;
+  state.devReloadTopic.value = isString(devReloadTopic)
+    ? devReloadTopic
+    : undefined;
 };
 
 const handleEvent =
   (state: UserRealtimeState) =>
-  (eventName: string, data: unknown): void => {
+  (eventName: string, data: RealtimeFrameData): void => {
     if (isSnapshotEvent(eventName, data)) {
       state.snapshots.set(data.topic, data);
       dispatchToHandlers(state, data.topic, data);
@@ -185,14 +185,14 @@ interface SessionGreeting {
 interface BufferedFrame {
   sessionId: string;
   eventName: string;
-  data: unknown;
+  data: RealtimeFrameData;
 }
 
 const readGreeting = async (
   response: Response,
 ): Promise<SessionGreeting | null> => {
   try {
-    return (await response.json()) as SessionGreeting | null;
+    return await response.json();
   } catch {
     return null;
   }
@@ -203,6 +203,21 @@ const unauthorizedError = (): Error =>
     status: HTTP_UNAUTHORIZED,
   });
 
+const closeStraySession = (
+  sessionCloseUrl: string,
+  forConnection: string,
+  sessionId: string,
+) => {
+  void fetch(sessionCloseUrl, {
+    method: "POST",
+    headers: {
+      [CONNECTION_HEADER]: forConnection,
+      [SESSION_HEADER]: sessionId,
+    },
+    credentials: "include",
+  }).catch(() => {});
+};
+
 /**
  * Keeps a session of this tab on the browser's shared realtime connection
  * until cancelled: a new one each time the connection changes, its leader tab
@@ -218,23 +233,10 @@ const connectTab = (
   const retries = createReconnector();
   const sessionCloseUrl = `${baseUrl}${REALTIME_SESSION_CLOSE_PATH}`;
   let connectionId: string | undefined;
-  // Each opening attempt supersedes the previous one, which a renewal may
-  // leave in flight on the same connection.
+
   let attempt = 0;
-  // The session's first frames may come before the answer that names it.
-  let buffered: BufferedFrame[] | undefined;
 
-  // The backend ends only a session of the connection the request names.
-  const closeStraySession = (forConnection: string, sessionId: string) => {
-    void fetch(sessionCloseUrl, {
-      method: "POST",
-      headers: {
-        [CONNECTION_HEADER]: forConnection,
-        [SESSION_HEADER]: sessionId,
-      },
-      credentials: "include",
-    }).catch(() => {});
-  };
+  let buffered: BufferedFrame[] | undefined;
 
   const adopt = (forConnection: string, greeting: SessionGreeting) => {
     const sessionId = String(greeting.sessionId);
@@ -264,7 +266,7 @@ const connectTab = (
     try {
       response = await fetch(`${baseUrl}${REALTIME_SESSION_PATH}`, {
         method: "POST",
-        // The dashboard's backend proxy relays this header by name.
+
         headers: { [CONNECTION_HEADER]: forConnection },
         credentials: "include",
       });
@@ -275,8 +277,8 @@ const connectTab = (
     const greeting = response.ok ? await readGreeting(response) : null;
     const sessionId = greeting?.sessionId;
     if (!isCurrent()) {
-      if (typeof sessionId === "string") {
-        closeStraySession(forConnection, sessionId);
+      if (isString(sessionId)) {
+        closeStraySession(sessionCloseUrl, forConnection, sessionId);
       }
       return;
     }
@@ -288,10 +290,8 @@ const connectTab = (
       retry();
       return;
     }
-    // The backend does not know the connection: it went, or this request
-    // reached an instance that does not hold it. The leader opens a new one,
-    // which this tab opens its session on; the backoff spaces the attempts.
-    if (typeof sessionId !== "string") {
+
+    if (!isString(sessionId)) {
       buffered = undefined;
       retries.schedule(() => {
         if (isCurrent()) connection.reopen(forConnection);
@@ -301,13 +301,11 @@ const connectTab = (
     adopt(forConnection, greeting!);
   };
 
-  // A new session on the connection the tab keeps: the backend ended the
-  // current one alone, or the tab's account or workspace changed.
   const renewSession = () => {
     if (retries.isCancelled() || !connectionId) return;
     const sessionId = state.sessionId.value;
     if (sessionId) {
-      closeStraySession(connectionId, sessionId);
+      closeStraySession(sessionCloseUrl, connectionId, sessionId);
       callbacks.onDisconnected();
     }
     void openSession(connectionId);
@@ -325,7 +323,6 @@ const connectTab = (
       if (next) void openSession(next);
     },
     onFrame: (sessionId, eventName, data) => {
-      // The connection's own frames reach a tab once it has a session on it.
       if (sessionId === undefined) {
         if (state.sessionId.value) dispatch(eventName, data);
         return;
@@ -363,13 +360,13 @@ interface PageSubscriptionAnswer {
 const readPageTopics = async (response: Response): Promise<string[]> => {
   let answer: PageSubscriptionAnswer | null;
   try {
-    answer = (await response.json()) as PageSubscriptionAnswer | null;
+    answer = await response.json();
   } catch {
     return [];
   }
   const topics = answer?.topics;
   return Array.isArray(topics)
-    ? topics.filter((topic): topic is string => typeof topic === "string")
+    ? topics.filter((topic): topic is string => isString(topic))
     : [];
 };
 
@@ -381,7 +378,7 @@ const callPageEndpoint = async (
 ): Promise<string[]> => {
   const sessionId = state.sessionId.value;
   if (!sessionId) return [];
-  const headers: Record<string, string> = { [SESSION_HEADER]: sessionId };
+  const headers = { [SESSION_HEADER]: sessionId };
   const url = pageId
     ? `${baseUrl}${REALTIME_SUBSCRIBE_PATH_PREFIX}${pageId}`
     : `${baseUrl}${REALTIME_UNSUBSCRIBE_PATH}`;
@@ -402,8 +399,7 @@ const applyDesiredPage = async (
   if (state.appliedPageId.value === desired) return;
   if (!sessionId) return;
   const topics = await callPageEndpoint(state, desired, baseUrl);
-  // A reconnect during the call replaced the session: the page is applied to
-  // the dead one, and the new one still needs it.
+
   if (state.sessionId.value !== sessionId) return;
   state.appliedPageId.value = desired;
   state.pageTopics.value = topics;
@@ -467,11 +463,9 @@ const buildApi = (): UserRealtimeApi => {
     SessionScopeFields
   >();
   const { refreshSession, redirectToAuth } = useSessionRecovery();
-  const baseUrl = config.public.dms.baseURL as string;
+  const baseUrl = config.public.dms.baseURL;
 
   if (!import.meta.env.SSR) {
-    // One connection per user: the tabs of another user (an account
-    // switched in one tab) share theirs, and never read this one's events.
     watch(
       () => (loggedIn.value ? String(user.value?._id ?? "") : undefined),
       (userKey) => {
@@ -491,8 +485,7 @@ const buildApi = (): UserRealtimeApi => {
       },
       { immediate: true },
     );
-    // A switch of account or workspace within the same user: the tab's session
-    // is renewed on the connection it already shares.
+
     watch(
       () => sessionScopeOf(session?.value),
       () => state.connection?.renewSession(),

package/frontend-vue/layers/dms-core/app/composables/translation/useComposedText.ts

@@ -8,7 +8,6 @@ import { getPluginI18n } from "./useTranslation";
 type ComposedTextI18n = Pick<ReturnType<typeof useI18n>, "t" | "locale">;
 
 function composedTextOf({ t, locale }: ComposedTextI18n) {
-  // vue-i18n reads a third argument as a plural count only when there is one.
   const translate: ComposedTextTranslate = (key, named, plural) =>
     plural === undefined ? t(key, named) : t(key, named, plural);
 

package/frontend-vue/layers/dms-core/app/composables/translation/useTranslation.ts

@@ -1,9 +1,9 @@
+import type { NamedValue } from "vue-i18n";
+import { isString } from "../../utils/type-check";
+
 const TRANSLATION_KEY_PREFIX = "$";
 
-export type I18nTranslate = (
-  key: string,
-  params: Record<string, unknown>,
-) => string;
+export type I18nTranslate = (key: string, params: NamedValue) => string;
 
 /**
  * i18n access for DMS app plugins, where `useI18n()` is unavailable: returns
@@ -34,7 +34,7 @@ export function readTranslationKey(value: string) {
 export function resolveI18nKey(
   translate: I18nTranslate,
   key: string,
-  params?: Record<string, unknown> | null,
+  params?: Parameters<I18nTranslate>[1] | null,
 ): string {
   const marked = readTranslationKey(key);
   if (marked.isKey) {
@@ -55,10 +55,10 @@ export function resolveI18nKey(
  */
 export function resolveApiMessage(
   translate: I18nTranslate,
-  message: unknown,
-  params?: Record<string, unknown> | null,
+  message: Parameters<typeof isString>[0],
+  params?: Parameters<I18nTranslate>[1] | null,
 ): string {
-  const text = typeof message === "string" ? message : String(message);
+  const text = isString(message) ? message : String(message);
   const marked = readTranslationKey(text);
   const translated = translate(marked.key, params ?? {});
 
@@ -75,7 +75,7 @@ export function resolveApiMessage(
 export function resolveOptionalI18nKey(
   translate: I18nTranslate,
   key: string | undefined,
-  params?: Record<string, unknown> | null,
+  params?: Parameters<I18nTranslate>[1] | null,
 ): string | undefined {
   if (!key) {
     return undefined;
@@ -92,13 +92,16 @@ export function resolveOptionalI18nKey(
 type ComposerTranslate = ReturnType<typeof useI18n>["t"];
 
 function translationOf(t: ComposerTranslate) {
-  function processI18n(key: string, params?: Record<string, unknown> | null) {
+  function processI18n(
+    key: string,
+    params?: Parameters<I18nTranslate>[1] | null,
+  ) {
     return resolveI18nKey(t, key, params);
   }
 
   function processApiMessage(
-    message: unknown,
-    params?: Record<string, unknown> | null,
+    message: Parameters<typeof resolveApiMessage>[1],
+    params?: Parameters<I18nTranslate>[1] | null,
   ) {
     return resolveApiMessage(t, message, params);
   }

package/frontend-vue/layers/dms-core/app/composables/useApiError.ts

@@ -1,3 +1,5 @@
+import { isObject, isString } from "../utils/type-check";
+
 interface Options {
   context?: string;
   title?: string;
@@ -17,20 +19,18 @@ const FALLBACK_ERROR_KEY = "error.500.description";
 const CLIENT_ERROR_STATUS_MIN = 400;
 const CLIENT_ERROR_STATUS_MAX = 499;
 
-function isApiError(error: unknown): error is ApiError {
-  return typeof error === "object" && error !== null;
+function isApiError(
+  error: Parameters<typeof resolveApiErrorTitle>[0],
+): error is ApiError {
+  return isObject(error) && error !== null;
 }
 
 function resolveDescription(error: ApiError): string {
-  const errorData = error.data as Record<string, unknown> | string | undefined;
-  if (
-    errorData &&
-    typeof errorData === "object" &&
-    typeof errorData.message === "string"
-  ) {
+  const errorData = error.data;
+  if (errorData && isObject(errorData) && isString(errorData.message)) {
     return errorData.message;
   }
-  if (typeof errorData === "string") {
+  if (isString(errorData)) {
     return errorData;
   }
   return FALLBACK_ERROR_KEY;
@@ -48,7 +48,9 @@ function isClientErrorStatus(status: number | undefined): boolean {
  * The i18n title key matching a fetch error's HTTP status: a 4xx is a request
  * the backend refused, anything else (5xx, network failure) a server error.
  */
-export function resolveApiErrorTitle(error: unknown): string {
+export function resolveApiErrorTitle(
+  error: Parameters<typeof isObject>[0],
+): string {
   const status = isApiError(error)
     ? (error.statusCode ?? error.status)
     : undefined;
@@ -61,11 +63,16 @@ export function resolveApiErrorTitle(error: unknown): string {
  * Extract the backend's error body from a fetch error — an i18n message key
  * per the API error contract — falling back to the generic 500 key.
  */
-export function resolveApiErrorMessage(error: unknown): string {
+export function resolveApiErrorMessage(
+  error: Parameters<typeof resolveApiErrorTitle>[0],
+): string {
   return isApiError(error) ? resolveDescription(error) : FALLBACK_ERROR_KEY;
 }
 
-export function useApiError(error: unknown, options?: Options) {
+export function useApiError(
+  error: Parameters<typeof resolveApiErrorTitle>[0],
+  options?: Options,
+) {
   const toast = useToast();
   const { processApiMessage } = getAppTranslation();
 

package/frontend-vue/layers/dms-core/app/composables/useEventedAction.ts

@@ -1,3 +1,5 @@
+import type { ComponentEventData } from "../types/component";
+
 interface EventedActionOptions {
   componentId?: string;
   events?: {
@@ -8,9 +10,10 @@ interface EventedActionOptions {
 }
 
 interface ExecuteOptions<TResult> {
-  startPayload?: unknown;
-  successPayload?: (result: TResult) => unknown;
-  errorPayload?: (error: unknown) => unknown;
+  startPayload?: ComponentEventData["data"];
+  successPayload?: (result: TResult) => ComponentEventData["data"];
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- JavaScript actions may reject with any value; neither Promise<TResult> nor the component-event owner provides a narrower rejection type.
+  errorPayload?: (error: unknown) => ComponentEventData["data"];
 }
 
 export function useEventedAction<TResult = unknown>(
@@ -19,7 +22,10 @@ export function useEventedAction<TResult = unknown>(
   const { sendComponentEvent } = useComponentEvent();
   const isLoading = ref(false);
 
-  function dispatchEvent(eventName: string | undefined, payload: unknown) {
+  function dispatchEvent(
+    eventName: string | undefined,
+    payload: ComponentEventData["data"],
+  ) {
     if (!eventName || !options.componentId) return;
     sendComponentEvent(eventName, options.componentId, payload);
   }