@tthr/vue 0.0.84 → 0.0.86

package/nuxt/module.js

@@ -62,6 +62,7 @@ export default defineNuxtModule({
             wsUrl,
         };
         // Add server API routes for proxying Tether requests
+        // Use .js — Nitro's rollup can't parse .ts from node_modules
         addServerHandler({
             route: '/api/_tether/query',
             method: 'post',
@@ -106,7 +107,7 @@ export default defineNuxtModule({
             filePath: resolver.resolve('./runtime/components/TetherWelcome.vue'),
         });
         // Auto-import server utilities (available in server/ directory)
-        // Use .js extensions to ensure the pre-built files are used
+        // Use .js — Nitro's rollup can't parse .ts from node_modules
         addServerImports([
             {
                 name: 'useTetherServer',
@@ -132,7 +133,6 @@ export default defineNuxtModule({
         // This auto-connects to Tether when the server starts
         nuxt.hook('nitro:config', (nitroConfig) => {
             nitroConfig.plugins = nitroConfig.plugins || [];
-            // Use pre-compiled JS - Nitro can parse this without TypeScript plugins
             nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugins/cron.js'));
             // Ensure Nitro inlines and transpiles the plugin from node_modules
             nitroConfig.externals = nitroConfig.externals || {};

package/nuxt/module.ts

@@ -78,6 +78,7 @@ export default defineNuxtModule<TetherModuleOptions>({
     };
 
     // Add server API routes for proxying Tether requests
+    // Use .js — Nitro's rollup can't parse .ts from node_modules
     addServerHandler({
       route: '/api/_tether/query',
       method: 'post',
@@ -127,7 +128,7 @@ export default defineNuxtModule<TetherModuleOptions>({
     });
 
     // Auto-import server utilities (available in server/ directory)
-    // Use .js extensions to ensure the pre-built files are used
+    // Use .js — Nitro's rollup can't parse .ts from node_modules
     addServerImports([
       {
         name: 'useTetherServer',
@@ -155,7 +156,6 @@ export default defineNuxtModule<TetherModuleOptions>({
     // This auto-connects to Tether when the server starts
     nuxt.hook('nitro:config' as any, (nitroConfig: any) => {
       nitroConfig.plugins = nitroConfig.plugins || [];
-      // Use pre-compiled JS - Nitro can parse this without TypeScript plugins
       nitroConfig.plugins.push(resolver.resolve('./runtime/server/plugins/cron.js'));
 
       // Ensure Nitro inlines and transpiles the plugin from node_modules

package/nuxt/runtime/composables.ts

@@ -0,0 +1,638 @@
+/**
+ * Nuxt composables for Tether
+ *
+ * These are auto-imported when using the Tether Nuxt module.
+ * Queries and mutations are executed server-side to keep API keys secure.
+ * WebSocket subscriptions run client-side for realtime updates - automatically!
+ */
+
+import { ref, onMounted, onUnmounted, computed, watch, toRaw, isRef, type Ref, type ComputedRef } from 'vue';
+import { useAsyncData } from '#imports';
+
+/**
+ * Recursively unwrap Vue reactive proxies and refs so the value is
+ * safe to pass to JSON.stringify (no circular Vue internals).
+ */
+function toPlainArgs<T>(value: T): T {
+  if (value == null || typeof value !== 'object') return value;
+  const raw = toRaw(value);
+  if (isRef(raw)) return toPlainArgs((raw as Ref).value) as T;
+  if (Array.isArray(raw)) return raw.map(toPlainArgs) as T;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(raw as Record<string, unknown>)) {
+    out[key] = toPlainArgs((raw as Record<string, unknown>)[key]);
+  }
+  return out as T;
+}
+
+// ============================================================================
+// Shared WebSocket Connection Manager
+// ============================================================================
+
+interface SubscriptionCallback {
+  onData: (data: unknown) => void;
+  onInvalidate: () => void;
+}
+
+interface ConnectionManager {
+  ws: WebSocket | null;
+  subscriptions: Map<string, SubscriptionCallback>;
+  isConnecting: boolean;
+  reconnectTimeout: ReturnType<typeof setTimeout> | null;
+  heartbeatInterval: ReturnType<typeof setInterval> | null;
+  heartbeatTimeout: ReturnType<typeof setTimeout> | null;
+  awaitingPong: boolean;
+  refCount: number;
+}
+
+// Singleton connection manager (client-side only)
+let connectionManager: ConnectionManager | null = null;
+
+function getConnectionManager(): ConnectionManager {
+  if (!connectionManager) {
+    connectionManager = {
+      ws: null,
+      subscriptions: new Map(),
+      isConnecting: false,
+      reconnectTimeout: null,
+      heartbeatInterval: null,
+      heartbeatTimeout: null,
+      awaitingPong: false,
+      refCount: 0,
+    };
+  }
+  return connectionManager;
+}
+
+const HEARTBEAT_INTERVAL = 25000;
+const HEARTBEAT_TIMEOUT = 15000;
+
+function startHeartbeat(cm: ConnectionManager) {
+  stopHeartbeat(cm);
+  cm.heartbeatInterval = setInterval(() => {
+    if (cm.ws?.readyState === WebSocket.OPEN) {
+      cm.awaitingPong = true;
+      cm.ws.send(JSON.stringify({ type: 'ping' }));
+      cm.heartbeatTimeout = setTimeout(() => {
+        if (cm.awaitingPong) {
+          console.warn('[Tether] Heartbeat timeout - forcing reconnect');
+          cm.ws?.close();
+        }
+      }, HEARTBEAT_TIMEOUT);
+    }
+  }, HEARTBEAT_INTERVAL);
+}
+
+function stopHeartbeat(cm: ConnectionManager) {
+  if (cm.heartbeatInterval) {
+    clearInterval(cm.heartbeatInterval);
+    cm.heartbeatInterval = null;
+  }
+  if (cm.heartbeatTimeout) {
+    clearTimeout(cm.heartbeatTimeout);
+    cm.heartbeatTimeout = null;
+  }
+  cm.awaitingPong = false;
+}
+
+function connectWebSocket(cm: ConnectionManager) {
+  if (cm.isConnecting) return;
+  if (cm.ws && (cm.ws.readyState === WebSocket.OPEN || cm.ws.readyState === WebSocket.CONNECTING)) {
+    return;
+  }
+
+  const config = (window as any).__TETHER_CONFIG__;
+  if (!config?.wsUrl || !config?.projectId) {
+    console.warn('[Tether] WebSocket config not available');
+    return;
+  }
+
+  cm.isConnecting = true;
+  const wsUrl = `${config.wsUrl}/ws/${config.projectId}`;
+  cm.ws = new WebSocket(wsUrl);
+
+  cm.ws.onopen = () => {
+    cm.isConnecting = false;
+  };
+
+  cm.ws.onmessage = (event) => {
+    try {
+      const message = JSON.parse(event.data);
+
+      if (message.type === 'connected') {
+        startHeartbeat(cm);
+        // Re-subscribe all active subscriptions
+        for (const [subscriptionId, _callback] of cm.subscriptions) {
+          const [queryName, argsJson] = subscriptionId.split('::');
+          const args = argsJson ? JSON.parse(argsJson) : undefined;
+          cm.ws?.send(JSON.stringify({
+            type: 'subscribe',
+            id: subscriptionId,
+            query: queryName,
+            args,
+          }));
+        }
+      } else if (message.type === 'data') {
+        const callback = cm.subscriptions.get(message.id);
+        if (callback) {
+          callback.onData(message.data);
+        }
+      } else if (message.type === 'invalidate') {
+        const callback = cm.subscriptions.get(message.id);
+        if (callback) {
+          callback.onInvalidate();
+        }
+      } else if (message.type === 'pong') {
+        cm.awaitingPong = false;
+        if (cm.heartbeatTimeout) {
+          clearTimeout(cm.heartbeatTimeout);
+          cm.heartbeatTimeout = null;
+        }
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  };
+
+  cm.ws.onclose = () => {
+    cm.isConnecting = false;
+    stopHeartbeat(cm);
+    // Reconnect if there are still active subscriptions
+    if (cm.subscriptions.size > 0) {
+      cm.reconnectTimeout = setTimeout(() => connectWebSocket(cm), 3000);
+    }
+  };
+
+  cm.ws.onerror = () => {
+    cm.isConnecting = false;
+    cm.ws?.close();
+  };
+}
+
+function subscribe(
+  queryName: string,
+  args: Record<string, unknown> | undefined,
+  callbacks: SubscriptionCallback
+): () => void {
+  const cm = getConnectionManager();
+  const plainArgs = toPlainArgs(args);
+  const subscriptionId = `${queryName}::${JSON.stringify(plainArgs ?? {})}`;
+
+  cm.subscriptions.set(subscriptionId, callbacks);
+  cm.refCount++;
+
+  // Connect if not already connected
+  if (!cm.ws || cm.ws.readyState === WebSocket.CLOSED) {
+    connectWebSocket(cm);
+  } else if (cm.ws.readyState === WebSocket.OPEN) {
+    // Already connected - subscribe immediately
+    cm.ws.send(JSON.stringify({
+      type: 'subscribe',
+      id: subscriptionId,
+      query: queryName,
+      args: plainArgs,
+    }));
+  }
+
+  // Return cleanup function
+  return () => {
+    cm.subscriptions.delete(subscriptionId);
+    cm.refCount--;
+
+    // Unsubscribe from server
+    if (cm.ws?.readyState === WebSocket.OPEN) {
+      cm.ws.send(JSON.stringify({
+        type: 'unsubscribe',
+        id: subscriptionId,
+      }));
+    }
+
+    // Close connection if no more subscriptions
+    if (cm.refCount === 0) {
+      if (cm.reconnectTimeout) {
+        clearTimeout(cm.reconnectTimeout);
+        cm.reconnectTimeout = null;
+      }
+      stopHeartbeat(cm);
+      cm.ws?.close();
+      cm.ws = null;
+    }
+  };
+}
+
+// Handle visibility changes globally
+if (typeof window !== 'undefined') {
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'visible') {
+      const cm = connectionManager;
+      if (cm && cm.subscriptions.size > 0) {
+        if (!cm.ws || cm.ws.readyState === WebSocket.CLOSED) {
+          if (cm.reconnectTimeout) {
+            clearTimeout(cm.reconnectTimeout);
+            cm.reconnectTimeout = null;
+          }
+          connectWebSocket(cm);
+        }
+      }
+    }
+  });
+}
+
+// ============================================================================
+// Query Composable
+// ============================================================================
+
+/**
+ * Query state returned by useQuery
+ */
+export interface QueryState<T> {
+  data: Ref<T | undefined>;
+  error: Ref<Error | null>;
+  isLoading: ComputedRef<boolean>;
+  isConnected: Ref<boolean>;
+  refetch: () => Promise<void>;
+}
+
+/**
+ * Thenable query state — can be awaited or destructured directly.
+ * When awaited, resolves after the initial fetch completes (data is populated).
+ * When destructured without await, data starts as undefined and populates reactively.
+ */
+export type AsyncQueryState<T> = QueryState<T> & PromiseLike<QueryState<T>>;
+
+/**
+ * Query function reference
+ */
+export interface QueryFunction<TArgs = void, TResult = unknown> {
+  _name: string;
+  _args?: TArgs;
+  _result?: TResult;
+}
+
+/**
+ * Reactive query composable with automatic realtime updates
+ *
+ * Uses Nuxt's useAsyncData internally for proper SSR support.
+ * Data is fetched on the server and hydrated on the client.
+ * Automatically subscribes to WebSocket updates for realtime sync.
+ *
+ * Can be used with or without await:
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * // Reactive — data fills in asynchronously, updates in realtime
+ * const { data: posts, isLoading, isConnected } = useQuery(api.posts.list);
+ *
+ * // Awaited — data is populated when the promise resolves, still updates in realtime
+ * const { data: posts } = await useQuery(api.posts.list);
+ * </script>
+ * ```
+ */
+export function useQuery<TArgs, TResult>(
+  query: QueryFunction<TArgs, TResult> | string,
+  args?: TArgs
+): AsyncQueryState<TResult> {
+  const queryName = typeof query === 'string' ? query : query._name;
+  const plainArgs = toPlainArgs(args);
+  const queryArgs = plainArgs as Record<string, unknown> | undefined;
+
+  // Create a unique key for this query based on name and args
+  const queryKey = `tether-${queryName}-${JSON.stringify(plainArgs ?? {})}`;
+
+  // Track WebSocket connection state
+  const isConnected = ref(false);
+
+  // Use Nuxt's useAsyncData for proper SSR support
+  const { data, error: asyncError, status, refresh } = useAsyncData<TResult>(
+    queryKey,
+    async () => {
+      const response = await $fetch<{ data: TResult }>('/api/_tether/query', {
+        method: 'POST',
+        body: {
+          function: queryName,
+          args: plainArgs,
+        },
+      });
+      return response.data;
+    },
+    {
+      dedupe: 'cancel',
+    }
+  );
+
+  // Wrap the error as a computed ref
+  const error = computed(() => {
+    if (asyncError.value) {
+      return asyncError.value instanceof Error
+        ? asyncError.value
+        : new Error(String(asyncError.value));
+    }
+    return null;
+  });
+
+  // Compute isLoading from status
+  const isLoading = computed(() => status.value === 'pending');
+
+  // Refetch function
+  const refetch = async () => {
+    await refresh();
+  };
+
+  // Auto-subscribe on client side
+  if (import.meta.client) {
+    let unsubscribe: (() => void) | null = null;
+
+    onMounted(() => {
+      unsubscribe = subscribe(queryName, queryArgs, {
+        onData: (newData) => {
+          data.value = newData as TResult;
+        },
+        onInvalidate: () => {
+          refresh();
+        },
+      });
+
+      // Track connection state
+      const checkConnection = () => {
+        const cm = connectionManager;
+        isConnected.value = cm?.ws?.readyState === WebSocket.OPEN ?? false;
+      };
+      checkConnection();
+      const interval = setInterval(checkConnection, 1000);
+      onUnmounted(() => clearInterval(interval));
+    });
+
+    onUnmounted(() => {
+      unsubscribe?.();
+    });
+  }
+
+  // Build the synchronous return object
+  const state: QueryState<TResult> = {
+    data: data as Ref<TResult | undefined>,
+    error: error as unknown as Ref<Error | null>,
+    isLoading,
+    isConnected,
+    refetch,
+  };
+
+  // Create a promise that resolves when the initial fetch completes.
+  // On SSR or hydration, status is already not 'pending', so it resolves immediately.
+  // On client-side navigation, it waits for the fetch to finish.
+  const initialFetchPromise = new Promise<QueryState<TResult>>((resolve) => {
+    if (status.value !== 'pending') {
+      resolve(state);
+      return;
+    }
+    const unwatch = watch(status, (newStatus) => {
+      if (newStatus !== 'pending') {
+        unwatch();
+        resolve(state);
+      }
+    });
+  });
+
+  // Merge the promise onto the state object so it's both destructurable and thenable
+  return Object.assign(initialFetchPromise, state) as AsyncQueryState<TResult>;
+}
+
+// ============================================================================
+// Standalone Query Function
+// ============================================================================
+
+/**
+ * Execute a query and return raw data directly.
+ *
+ * Unlike useQuery, this does NOT set up reactive state or WebSocket subscriptions.
+ * Use this in event handlers, utilities, or anywhere you need a one-shot data fetch.
+ * Proxies through the Nuxt server route to keep API keys secure.
+ *
+ * @example
+ * ```ts
+ * // In an event handler
+ * async function loadMessages(channelId: string) {
+ *   const messages = await $query(api.messages.listByChannel, { channelId });
+ *   return messages;
+ * }
+ *
+ * // With a string name
+ * const posts = await $query('posts.list', { limit: 10 });
+ * ```
+ */
+export async function $query<TArgs, TResult>(
+  query: QueryFunction<TArgs, TResult> | string,
+  args?: TArgs
+): Promise<TResult> {
+  const queryName = typeof query === 'string' ? query : query._name;
+  const plainArgs = toPlainArgs(args);
+
+  const response = await $fetch<{ data: TResult }>('/api/_tether/query', {
+    method: 'POST',
+    body: {
+      function: queryName,
+      args: plainArgs,
+    },
+  });
+
+  return response.data;
+}
+
+// ============================================================================
+// Mutation Composable
+// ============================================================================
+
+/**
+ * Mutation state returned by useMutation
+ */
+export interface MutationState<TArgs, TResult> {
+  data: Ref<TResult | undefined>;
+  error: Ref<Error | null>;
+  isPending: Ref<boolean>;
+  mutate: (args: TArgs) => Promise<TResult>;
+  reset: () => void;
+}
+
+/**
+ * Mutation function reference
+ */
+export interface MutationFunction<TArgs = void, TResult = unknown> {
+  _name: string;
+  _args?: TArgs;
+  _result?: TResult;
+}
+
+/**
+ * Mutation composable
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { mutate: createPost, isPending } = useMutation(api.posts.create);
+ *
+ * async function handleSubmit() {
+ *   await createPost({ title: 'Hello', content: '...' });
+ *   // All useQuery subscribers automatically update!
+ * }
+ * </script>
+ * ```
+ */
+export function useMutation<TArgs, TResult>(
+  mutation: MutationFunction<TArgs, TResult> | string
+): MutationState<TArgs, TResult> {
+  const mutationName = typeof mutation === 'string' ? mutation : mutation._name;
+  const data = ref<TResult>();
+  const error = ref<Error | null>(null);
+  const isPending = ref(false);
+
+  const mutate = async (args: TArgs): Promise<TResult> => {
+    try {
+      isPending.value = true;
+      error.value = null;
+
+      const response = await $fetch<{ data: TResult }>('/api/_tether/mutation', {
+        method: 'POST',
+        body: {
+          function: mutationName,
+          args: toPlainArgs(args),
+        },
+      });
+
+      data.value = response.data;
+      return response.data;
+    } catch (e) {
+      error.value = e instanceof Error ? e : new Error(String(e));
+      throw e;
+    } finally {
+      isPending.value = false;
+    }
+  };
+
+  const reset = () => {
+    data.value = undefined;
+    error.value = null;
+    isPending.value = false;
+  };
+
+  return {
+    data: data as Ref<TResult | undefined>,
+    error,
+    isPending,
+    mutate,
+    reset,
+  };
+}
+
+// ============================================================================
+// Standalone Mutation Function
+// ============================================================================
+
+/**
+ * Execute a mutation and return the result directly.
+ *
+ * Unlike useMutation, this does NOT set up reactive state.
+ * Use this in event handlers, utilities, or anywhere you need a one-shot mutation.
+ * Proxies through the Nuxt server route to keep API keys secure.
+ *
+ * @example
+ * ```ts
+ * // In an event handler
+ * async function handleCreate() {
+ *   const post = await $mutation(api.posts.create, { title: 'Hello' });
+ *   console.log('Created:', post);
+ * }
+ *
+ * // With a string name
+ * const result = await $mutation('posts.delete', { id: 123 });
+ * ```
+ */
+export async function $mutation<TArgs, TResult>(
+  mutation: MutationFunction<TArgs, TResult> | string,
+  args?: TArgs
+): Promise<TResult> {
+  const mutationName = typeof mutation === 'string' ? mutation : mutation._name;
+  const plainArgs = toPlainArgs(args);
+
+  const response = await $fetch<{ data: TResult }>('/api/_tether/mutation', {
+    method: 'POST',
+    body: {
+      function: mutationName,
+      args: plainArgs,
+    },
+  });
+
+  return response.data;
+}
+
+// ============================================================================
+// Manual Subscription (for advanced use cases)
+// ============================================================================
+
+/**
+ * Subscription handler options
+ */
+export interface SubscriptionHandlers {
+  /** Called when fresh data is received from the server */
+  onData?: (data: unknown) => void;
+  /** Called when server invalidates the subscription (signals to refetch) */
+  onInvalidate?: () => void;
+}
+
+/**
+ * Manual WebSocket subscription composable
+ *
+ * NOTE: You typically don't need this! useQuery automatically subscribes to updates.
+ * This is only for advanced use cases where you need custom subscription handling.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * // For custom subscription handling (rare)
+ * const { isConnected } = useTetherSubscription('custom.query', {}, {
+ *   onData: (data) => console.log('Got data:', data),
+ *   onInvalidate: () => console.log('Data invalidated'),
+ * });
+ * </script>
+ * ```
+ */
+export function useTetherSubscription(
+  queryName: string,
+  args: Record<string, unknown> | undefined,
+  handlers: SubscriptionHandlers | ((data?: unknown) => void)
+): { isConnected: Ref<boolean> } {
+  const isConnected = ref(false);
+
+  // Normalize handlers
+  const onData = typeof handlers === 'function'
+    ? handlers
+    : handlers.onData ?? (() => {});
+  const onInvalidate = typeof handlers === 'function'
+    ? () => handlers(undefined)
+    : handlers.onInvalidate ?? (() => {});
+
+  if (import.meta.client) {
+    let unsubscribe: (() => void) | null = null;
+
+    onMounted(() => {
+      unsubscribe = subscribe(queryName, args, {
+        onData,
+        onInvalidate,
+      });
+
+      // Track connection state
+      const checkConnection = () => {
+        const cm = connectionManager;
+        isConnected.value = cm?.ws?.readyState === WebSocket.OPEN ?? false;
+      };
+      checkConnection();
+      const interval = setInterval(checkConnection, 1000);
+      onUnmounted(() => clearInterval(interval));
+    });
+
+    onUnmounted(() => {
+      unsubscribe?.();
+    });
+  }
+
+  return { isConnected };
+}