@spooky-sync/client-solid 0.0.1-canary.113 → 0.0.1-canary.117

package/src/lib/create-preload.ts

@@ -0,0 +1,111 @@
+import type {
+  ColumnSchema,
+  FinalQuery,
+  SchemaStructure,
+  TableNames,
+} from '@spooky-sync/query-builder';
+import { createEffect, useContext } from 'solid-js';
+import { SyncedDb } from '..';
+import type { Sp00kyQueryResultPromise, PreloadOptions as CorePreloadOptions } from '@spooky-sync/core';
+import { Sp00kyContext } from './context';
+
+type PreloadArg<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+> =
+  | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+  | (() =>
+      | FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise>
+      | null
+      | undefined);
+
+type PreloadOptions = CorePreloadOptions & {
+  /** Only preload while this returns true (defaults to always). */
+  enabled?: () => boolean;
+};
+
+// Overload: context-based (no explicit db)
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: PreloadOptions,
+): void;
+
+// Overload: explicit db
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  db: SyncedDb<S>,
+  finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  options?: PreloadOptions,
+): void;
+
+/**
+ * Reactive, fire-and-forget prewarm. Resolves the query (calling it if it's a
+ * function so it tracks reactive deps), dedupes on the query's stable identity
+ * hash, and warms it into the local cache via `db.preload`. No subscription and
+ * no cleanup: preload registers nothing that needs tearing down.
+ *
+ * Typical use: inside a list row, preload the detail query the user is likely
+ * to open next, so navigation paints from cache instead of the network.
+ */
+export function createPreload<
+  S extends SchemaStructure,
+  TableName extends TableNames<S>,
+  T extends { columns: Record<string, ColumnSchema> },
+  RelatedFields extends Record<string, any>,
+  IsOne extends boolean,
+>(
+  dbOrQuery: SyncedDb<S> | PreloadArg<S, TableName, T, RelatedFields, IsOne>,
+  queryOrOptions?: PreloadArg<S, TableName, T, RelatedFields, IsOne> | PreloadOptions,
+  maybeOptions?: PreloadOptions,
+): void {
+  let db: SyncedDb<S>;
+  let finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>;
+  let options: PreloadOptions | undefined;
+
+  if (dbOrQuery instanceof SyncedDb) {
+    db = dbOrQuery;
+    finalQuery = queryOrOptions as PreloadArg<S, TableName, T, RelatedFields, IsOne>;
+    options = maybeOptions;
+  } else {
+    const contextDb = useContext(Sp00kyContext);
+    if (!contextDb) {
+      throw new Error(
+        'createPreload: No db argument provided and no Sp00kyContext found. ' +
+          'Either pass a SyncedDb instance or wrap your app in <Sp00kyProvider>.',
+      );
+    }
+    db = contextDb as SyncedDb<S>;
+    finalQuery = dbOrQuery;
+    options = queryOrOptions as PreloadOptions | undefined;
+  }
+
+  let prevHash: number | undefined;
+
+  createEffect(() => {
+    if (!(options?.enabled?.() ?? true)) return;
+
+    const query = typeof finalQuery === 'function' ? finalQuery() : finalQuery;
+    if (!query) return;
+
+    // Dedupe on the query's stable identity hash so a reactive re-run with an
+    // unchanged query doesn't refetch (the core also dedupes per session).
+    if (query.hash === prevHash) return;
+    prevHash = query.hash;
+
+    void db.getSp00ky().preload(query, { refresh: options?.refresh, staleTime: options?.staleTime });
+  });
+}