@instantdb/react 0.22.89 → 0.22.90-experimental.drewh-ssr.20286580593.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instantdb/react",
-  "version": "0.22.89",
+  "version": "0.22.90-experimental.drewh-ssr.20286580593.1",
   "description": "Instant DB for React",
   "homepage": "https://github.com/instantdb/instant/tree/main/client/packages/react",
   "repository": {
@@ -24,6 +24,16 @@
         "types": "./dist/commonjs/index.d.ts",
         "default": "./dist/commonjs/index.js"
       }
+    },
+    "./nextjs": {
+      "import": {
+        "types": "./dist/esm/next-ssr/index.d.ts",
+        "default": "./dist/esm/next-ssr/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/next-ssr/index.d.ts",
+        "default": "./dist/commonjs/next-ssr/index.js"
+      }
     }
   },
   "tshy": {
@@ -33,7 +43,8 @@
     "project": "./tsconfig.json",
     "exports": {
       "./package.json": "./package.json",
-      ".": "./src/index.ts"
+      ".": "./src/index.ts",
+      "./nextjs": "./src/next-ssr/index.tsx"
     }
   },
   "devDependencies": {
@@ -46,6 +57,7 @@
     "npm-run-all": "^4.1.5",
     "tshy": "^3.0.2",
     "typescript": "^5.9.3",
+    "next": "^15.5.6",
     "vite": "^5.2.0",
     "vitest": "^0.21.0"
   },
@@ -54,15 +66,15 @@
   },
   "dependencies": {
     "eventsource": "^4.0.0",
-    "@instantdb/core": "0.22.89",
-    "@instantdb/react-common": "0.22.89",
-    "@instantdb/version": "0.22.89"
+    "@instantdb/core": "0.22.90-experimental.drewh-ssr.20286580593.1",
+    "@instantdb/version": "0.22.90-experimental.drewh-ssr.20286580593.1",
+    "@instantdb/react-common": "0.22.90-experimental.drewh-ssr.20286580593.1"
   },
   "scripts": {
     "test": "vitest",
     "test:types": "tsc -p tsconfig.test.json --noEmit",
     "test:ci": "pnpm run test:types",
-    "check-exports": "attw --pack .",
+    "check-exports": "attw --profile node16 --pack .",
     "dev": "tsc --watch --preserveWatchOutput -p tsconfig.dev.json",
     "clean": "rm -rf dist",
     "build:tshy": "tshy",

package/src/index.ts

@@ -83,6 +83,7 @@ import {
   type SyncTableSyncTransaction,
   type SyncTableLoadFromStorage,
   type SyncTableSetupError,
+  createInstantRouteHandler,
 } from '@instantdb/core';
 
 import { InstantReactAbstractDatabase } from '@instantdb/react-common';
@@ -96,6 +97,7 @@ export {
   lookup,
   init,
   init_experimental,
+  createInstantRouteHandler,
   InstantReactWebDatabase,
   Cursors,
   i,

package/src/next-ssr/HydrationStreamProvider.tsx

@@ -0,0 +1,193 @@
+'use client';
+export const isServer = typeof window === 'undefined' || 'Deno' in globalThis;
+
+import { useServerInsertedHTML } from 'next/navigation.js';
+
+import * as React from 'react';
+import { htmlEscapeJsonString } from './htmlescape.js';
+
+const serializedSymbol = Symbol('serialized');
+
+interface DataTransformer {
+  serialize: (object: any) => any;
+  deserialize: (object: any) => any;
+}
+
+type Serialized<TData> = unknown & {
+  [serializedSymbol]: TData;
+};
+
+interface TypedDataTransformer<TData> {
+  serialize: (obj: TData) => Serialized<TData>;
+  deserialize: (obj: Serialized<TData>) => TData;
+}
+
+interface HydrationStreamContext<TShape> {
+  id: string;
+  stream: {
+    /**
+     * **Server method**
+     * Push a new entry to the stream
+     * Will be ignored on the client
+     */
+    push: (...shape: Array<TShape>) => void;
+  };
+}
+
+export interface HydrationStreamProviderProps<TShape> {
+  children: React.ReactNode;
+  /**
+   * Optional transformer to serialize/deserialize the data
+   * Example devalue, superjson et al
+   */
+  transformer?: DataTransformer;
+  /**
+   * **Client method**
+   * Called in the browser when new entries are received
+   */
+  onEntries: (entries: Array<TShape>) => void;
+  /**
+   * **Server method**
+   * onFlush is called on the server when the cache is flushed
+   */
+  onFlush?: () => Array<TShape>;
+  /**
+   * A nonce that'll allow the inline script to be executed when Content Security Policy is enforced
+   */
+  nonce?: string;
+}
+
+export function createHydrationStreamProvider<TShape>() {
+  const context = React.createContext<HydrationStreamContext<TShape>>(
+    null as any,
+  );
+  /**
+
+   * 1. (Happens on server): `useServerInsertedHTML()` is called **on the server** whenever a `Suspense`-boundary completes
+   *    - This means that we might have some new entries in the cache that needs to be flushed
+   *    - We pass these to the client by inserting a `<script>`-tag where we do `window[id].push(serializedVersionOfCache)`
+   * 2. (Happens in browser) In `useEffect()`:
+   *   - We check if `window[id]` is set to an array and call `push()` on all the entries which will call `onEntries()` with the new entries
+   *   - We replace `window[id]` with a `push()`-method that will be called whenever new entries are received
+   **/
+  function UseClientHydrationStreamProvider(props: {
+    children: React.ReactNode;
+    /**
+     * Optional transformer to serialize/deserialize the data
+     * Example devalue, superjson et al
+     */
+    transformer?: DataTransformer;
+    /**
+     * **Client method**
+     * Called in the browser when new entries are received
+     */
+    onEntries: (entries: Array<TShape>) => void;
+    /**
+     * **Server method**
+     * onFlush is called on the server when the cache is flushed
+     */
+    onFlush?: () => Array<TShape>;
+    /**
+     * A nonce that'll allow the inline script to be executed when Content Security Policy is enforced
+     */
+    nonce?: string;
+  }) {
+    // unique id for the cache provider
+    const id = `__RQ${React.useId()}`;
+    const idJSON = htmlEscapeJsonString(JSON.stringify(id));
+
+    const [transformer] = React.useState(
+      () =>
+        (props.transformer ?? {
+          // noop
+          serialize: (obj: any) => obj,
+          deserialize: (obj: any) => obj,
+        }) as unknown as TypedDataTransformer<TShape>,
+    );
+
+    // <server stuff>
+    const [stream] = React.useState<Array<TShape>>(() => {
+      if (!isServer) {
+        return {
+          push() {
+            // no-op on the client
+          },
+        } as unknown as Array<TShape>;
+      }
+      return [];
+    });
+    const count = React.useRef(0);
+    useServerInsertedHTML(() => {
+      // This only happens on the server
+      stream.push(...(props.onFlush?.() ?? []));
+
+      if (!stream.length) {
+        return null;
+      }
+      // console.log(`pushing ${stream.length} entries`)
+      const serializedCacheArgs = stream
+        .map((entry) => transformer.serialize(entry))
+        .map((entry) => JSON.stringify(entry))
+        .join(',');
+
+      // Flush stream
+      // eslint-disable-next-line react-hooks/immutability
+      stream.length = 0;
+
+      const html: Array<string> = [
+        `window[${idJSON}] = window[${idJSON}] || [];`,
+        `window[${idJSON}].push(${htmlEscapeJsonString(serializedCacheArgs)});`,
+      ];
+      return (
+        <script
+          key={count.current++}
+          nonce={props.nonce}
+          dangerouslySetInnerHTML={{
+            __html: html.join(''),
+          }}
+        />
+      );
+    });
+    // </server stuff>
+
+    // <client stuff>
+    // Setup and run the onEntries handler on the client only, but do it during
+    // the initial render so children have access to the data immediately
+    // This is important to avoid the client suspending during the initial render
+    // if the data has not yet been hydrated.
+    if (!isServer) {
+      const win = window as any;
+      if (!win[id]?.initialized) {
+        // Client: consume cache:
+        const onEntries = (...serializedEntries: Array<Serialized<TShape>>) => {
+          const entries = serializedEntries.map((serialized) =>
+            transformer.deserialize(serialized),
+          );
+          props.onEntries(entries);
+        };
+
+        const winStream: Array<Serialized<TShape>> = win[id] ?? [];
+
+        onEntries(...winStream);
+
+        // eslint-disable-next-line react-hooks/immutability
+        win[id] = {
+          initialized: true,
+          push: onEntries,
+        };
+      }
+    }
+    // </client stuff>
+
+    return (
+      <context.Provider value={{ stream, id }}>
+        {props.children}
+      </context.Provider>
+    );
+  }
+
+  return {
+    Provider: UseClientHydrationStreamProvider,
+    context,
+  };
+}

package/src/next-ssr/htmlescape.ts

@@ -0,0 +1,24 @@
+// --------------------------------------------------------------------------------
+//
+// copied from
+// https://github.com/vercel/next.js/blob/6bc07792a4462a4bf921a72ab30dc4ab2c4e1bda/packages/next/src/server/htmlescape.ts
+// License: https://github.com/vercel/next.js/blob/6bc07792a4462a4bf921a72ab30dc4ab2c4e1bda/packages/next/license.md
+//
+// --------------------------------------------------------------------------------
+
+// This utility is based on https://github.com/zertosh/htmlescape
+// License: https://github.com/zertosh/htmlescape/blob/0527ca7156a524d256101bb310a9f970f63078ad/LICENSE
+
+const ESCAPE_LOOKUP: Record<string, string> = {
+  '&': '\\u0026',
+  '>': '\\u003e',
+  '<': '\\u003c',
+  '\u2028': '\\u2028',
+  '\u2029': '\\u2029',
+};
+
+export const ESCAPE_REGEX = /[&><\u2028\u2029]/g;
+
+export function htmlEscapeJsonString(str: string): string {
+  return str.replace(ESCAPE_REGEX, (match) => ESCAPE_LOOKUP[match]!);
+}

package/src/next-ssr/index.tsx

@@ -0,0 +1,264 @@
+'use client';
+import {
+  AuthState,
+  FrameworkClient,
+  InstantConfig,
+  InstantSchemaDef,
+  InstantUnknownSchema,
+  InstaQLResponse,
+  PageInfoResponse,
+  RuleParams,
+  User,
+  ValidQuery,
+} from '@instantdb/core';
+import { createContext, useContext, useRef, useState } from 'react';
+import {
+  createHydrationStreamProvider,
+  isServer,
+} from './HydrationStreamProvider.tsx';
+import version from '../version.ts';
+
+import InstantReactWebDatabase from '../InstantReactWebDatabase.ts';
+import { InstantReactAbstractDatabase } from '@instantdb/react-common';
+
+type InstantSuspenseProviderProps<
+  Schema extends InstantSchemaDef<any, any, any>,
+> = {
+  nonce?: string;
+  children: React.ReactNode;
+  db?: InstantReactWebDatabase<Schema, any>;
+  config?: Omit<InstantConfig<any, any>, 'schema'> & {
+    schema: string;
+  };
+  user?: User | null;
+};
+
+const stream = createHydrationStreamProvider<any>();
+
+type SuspenseQueryContextValue = {
+  useSuspenseQuery: (query: any, opts?: SuspenseQueryOpts) => any;
+  ssrUser: User | null | undefined;
+};
+
+const SuspsenseQueryContext = createContext<SuspenseQueryContextValue | null>(
+  null,
+);
+
+// Creates a typed useSuspense hook
+export const createUseSuspenseQuery = <
+  Schema extends InstantSchemaDef<any, any, any>,
+  UseDates extends boolean,
+>(
+  _db: InstantReactWebDatabase<Schema, UseDates>,
+): (<Q extends ValidQuery<Q, Schema>>(
+  q: Q,
+  opts?: {
+    ruleParams: RuleParams;
+  },
+) => {
+  data: InstaQLResponse<Schema, Q, NonNullable<UseDates>>;
+  pageInfo?: PageInfoResponse<Q>;
+}) => {
+  return <Q extends ValidQuery<Q, Schema>>(q: any, opts: any) => {
+    const ctx = useContext(SuspsenseQueryContext);
+    if (!ctx) {
+      throw new Error(
+        'useSuspenseQuery must be used within a SuspenseQueryProvider',
+      );
+    }
+    return ctx.useSuspenseQuery(q, opts) as any;
+  };
+};
+
+type SuspenseQueryOpts = {
+  ruleParams: RuleParams;
+};
+
+export const InstantSuspenseProvider = (
+  props: InstantSuspenseProviderProps<any>,
+) => {
+  const clientRef = useRef<FrameworkClient | null>(null);
+
+  if (!props.db) {
+    throw new Error(
+      'Must provide either a db or config to InstantSuspenseProvider',
+    );
+  }
+
+  const db = useRef<InstantReactAbstractDatabase<any, any>>(props.db);
+
+  const [trackedKeys] = useState(() => new Set<string>());
+
+  if (!clientRef.current) {
+    if (props.user && !props.user.refresh_token) {
+      throw new Error(
+        'User must have a refresh_token field. Recieved: ' +
+          JSON.stringify(props.user, null, 2),
+      );
+    }
+    clientRef.current = new FrameworkClient({
+      token: props.user?.refresh_token,
+      db: db.current.core,
+    });
+  }
+
+  if (isServer) {
+    clientRef.current.subscribe((result) => {
+      const { queryHash } = result;
+      trackedKeys.add(queryHash);
+    });
+  }
+
+  const useSuspenseQuery = (query: any, opts: SuspenseQueryOpts) => {
+    const nonSuspenseResult = db.current.useQuery(query, {
+      ...opts,
+    });
+
+    if (nonSuspenseResult.data) {
+      return {
+        data: nonSuspenseResult.data,
+        pageInfo: nonSuspenseResult.pageInfo,
+      };
+    }
+
+    // should never happen (typeguard)
+    if (!clientRef.current) {
+      throw new Error('Client ref not set up');
+    }
+
+    let entry = clientRef.current.getExistingResultForQuery(query, {
+      ruleParams: opts?.ruleParams,
+    });
+
+    if (!entry) {
+      entry = clientRef.current!.query(query, opts);
+    }
+
+    if (entry.status === 'pending') {
+      throw entry.promise;
+    }
+
+    if (entry.status === 'error') {
+      throw entry.error;
+    }
+
+    if (entry.status === 'success') {
+      const data = entry.data;
+      const result = clientRef.current.completeIsomorphic(
+        query,
+        data.triples,
+        data.attrs,
+        data.pageInfo,
+      );
+
+      return result;
+    }
+  };
+
+  return (
+    <SuspsenseQueryContext.Provider
+      value={{ useSuspenseQuery, ssrUser: props.user }}
+    >
+      <stream.Provider
+        nonce={props.nonce}
+        onFlush={() => {
+          const toSend: { queryKey: string; value: any }[] = [];
+          for (const [key, value] of clientRef.current!.resultMap.entries()) {
+            if (trackedKeys.has(key) && value.status === 'success') {
+              toSend.push({
+                queryKey: key,
+                value: value.data,
+              });
+            }
+          }
+
+          trackedKeys.clear();
+          return toSend;
+        }}
+        onEntries={(entries) => {
+          entries.forEach((entry) => {
+            clientRef.current!.addQueryResult(entry.queryKey, entry.value);
+          });
+        }}
+      >
+        {props.children}
+      </stream.Provider>
+    </SuspsenseQueryContext.Provider>
+  );
+};
+
+/**
+ *
+ * The first step: init your application!
+ *
+ * Visit https://instantdb.com/dash to get your `appId` :)
+ *
+ * @example
+ *  import { init } from "@instantdb/react"
+ *
+ *  const db = init({ appId: "my-app-id" })
+ *
+ *  // You can also provide a schema for type safety and editor autocomplete!
+ *
+ *  import { init } from "@instantdb/react"
+ *  import schema from ""../instant.schema.ts";
+ *
+ *  const db = init({ appId: "my-app-id", schema })
+ *
+ *  // To learn more: https://instantdb.com/docs/modeling-data
+ */
+export function init<
+  Schema extends InstantSchemaDef<any, any, any> = InstantUnknownSchema,
+  UseDates extends boolean = false,
+>(
+  config: InstantConfig<Schema, UseDates>,
+): InstantNextDatabase<Schema, UseDates> {
+  return new InstantNextDatabase<Schema, UseDates>(config, {
+    '@instantdb/react': version,
+  });
+}
+
+export class InstantNextDatabase<
+  Schema extends InstantSchemaDef<any, any, any>,
+  UseDates extends boolean,
+> extends InstantReactWebDatabase<Schema, UseDates> {
+  public useSuspenseQuery = <Q extends ValidQuery<Q, Schema>>(
+    q: Q,
+    opts?: {
+      ruleParams: RuleParams;
+    },
+  ): {
+    data: InstaQLResponse<Schema, Q, NonNullable<UseDates>>;
+    pageInfo?: PageInfoResponse<Q>;
+  } => {
+    const ctx = useContext(SuspsenseQueryContext);
+    if (!ctx) {
+      throw new Error(
+        'useSuspenseQuery must be used within a SuspenseQueryProvider',
+      );
+    }
+    return ctx.useSuspenseQuery(q, opts) as any;
+  };
+
+  useAuth = (): AuthState => {
+    const ctx = useContext(SuspsenseQueryContext);
+    const realAuthResult = this._useAuth();
+    if (!ctx) {
+      return realAuthResult;
+    }
+
+    const { ssrUser } = ctx;
+    if (ssrUser === undefined) {
+      return realAuthResult;
+    }
+    if (realAuthResult.isLoading) {
+      return {
+        error: undefined,
+        isLoading: false,
+        user: ssrUser ?? undefined, // null -> undefined for the response
+      };
+    }
+
+    return realAuthResult;
+  };
+}

package/tsconfig.json

@@ -3,6 +3,7 @@
   "include": ["src"],
   "exclude": ["node_modules", "dist", "src/__types__"],
   "compilerOptions": {
+    "skipLibCheck": true,
     "outDir": "dist/tsc",
     "rewriteRelativeImportExtensions": true,
     "rootDir": "src",