@carvajalconsultants/headstart 1.0.4 → 1.0.6

package/README.md

@@ -16,15 +16,15 @@ This library is made up of:
    Specifically, the `graphile.config.ts` and `pgl.ts`. If you need WebSocket support, make sure to add a plugin in `graphile.config.ts` as per: https://postgraphile.org/postgraphile/next/subscriptions
 
 3. Install Headtart & URQL:
-```
-yarn add @carvajalconsultants/headstart urql @urql/exchange-graphcache
+```bash
+yarn add @carvajalconsultants/headstart urql @urql/exchange-graphcache @urql/exchange-auth
 ```
 
 4. Enable WebSockets in `app.config.ts` if you need it:
 
-```
+```typescript
 // app.config.ts
-import { defineConfig } from "@tanstack/start/config";
+import { defineConfig } from "@tanstack/react-start/config";
 
 export default defineConfig({
 	server: {
@@ -37,7 +37,7 @@ export default defineConfig({
 
 5. Make sure to add the `/api` endpoint to the grafserv configuration so that Ruru GraphQL client works correctly:
 
-```
+```typescript
 // graphile.config.ts
 const preset: GraphileConfig.Preset = {
     ...
@@ -52,9 +52,9 @@ const preset: GraphileConfig.Preset = {
 
 6. Add the api.ts file so that it calls our GraphQL handler. This will receive all GraphQL requests at the /api endpoint.
 
-```
+```typescript
 // app/api.ts
-import { defaultAPIFileRouteHandler } from "@tanstack/start/api";
+import { defaultAPIFileRouteHandler } from "@tanstack/react-start/api";
 import { createStartAPIHandler } from "@carvajalconsultants/headstart/server";
 import { pgl } from "../pgl";
 
@@ -63,7 +63,7 @@ export default createStartAPIHandler(pgl, defaultAPIFileRouteHandler);
 
 7. Now we need to configure URQL for client and server rendering, first we start with the server. Create this provider:
 
-```
+```typescript
 // app/graphql/serverProvider.tsx
 import { Client } from "urql";
 import { grafastExchange } from "@carvajalconsultants/headstart/server";
@@ -81,9 +81,90 @@ export const client = new Client({
 });
 ```
 
-8. Create the server side router which uses Grafast to execute queries:
+8. Now the client side for URQL:
+
+```typescript
+// app/graphql/clientProvider.tsx
+import { ssr } from "@carvajalconsultants/headstart/client";
+import { authExchange } from "@urql/exchange-auth";
+import { cacheExchange } from "@urql/exchange-graphcache";
+//import { relayPagination } from "@urql/exchange-graphcache/extras";
+import { Client, fetchExchange } from "urql";
 
+/**
+ * Creates an authentication exchange for handling secure GraphQL operations.
+ * This exchange ensures that all GraphQL requests are properly authenticated
+ * and handles authentication failures gracefully.
+ *
+ * @returns {Object} Authentication configuration object
+ * @returns {Function} .addAuthToOperation - Prepares operations with auth context
+ * @returns {Function} .didAuthError - Detects authentication failures after server request
+ * @returns {Function} .refreshAuth - Handles auth token refresh
+ */
+const auth = authExchange(async () => {
+  //TODO Implement authentication checking for the client s ide
+  await new Promise((resolve) => {
+    setTimeout(() => {
+      console.log("IMPLEMENT CLIENT AUTH CHECK");
+      resolve();
+    }, 2000);
+  });
+
+  return {
+    /**
+     * Processes each GraphQL operation to include authentication context.
+     * Currently configured as a pass-through as tokens are in cookies.
+     *
+     * @param {Operation} operation - The GraphQL operation to authenticate
+     * @returns {Operation} The operation with authentication context
+     */
+    addAuthToOperation: (operation) => operation,
+
+    /**
+     * Identifies when an operation has failed due to authentication issues.
+     * Used to trigger authentication refresh flows when needed.
+     *
+     * @param {Error} error - The GraphQL error response
+     * @returns {boolean} True if the error was caused by authentication failure
+     */
+    didAuthError: (error) => error.graphQLErrors.some((e) => e.extensions?.code === "FORBIDDEN"),
+
+    /**
+     * Handles refreshing authentication when it becomes invalid.
+     * Currently implemented as a no-op as token refresh is handled by getSession().
+     */
+    refreshAuth: async () => {
+      /* No-op, this is done in getSession() */
+    },
+  };
+});
+
+/**
+ * Configured GraphQL client for the application.
+ * Provides a centralized way to make authenticated GraphQL requests with
+ * proper caching and server-side rendering support.
+ */
+export const client = new Client({
+  url: "http://localhost:3000/api/graphql",
+  exchanges: [
+    cacheExchange({
+      resolvers: {
+        Query: {
+          // Implements relay-style pagination for fills pending match
+          //queryName: relayPagination(),
+        },
+      },
+    }),
+    auth,
+    ssr,
+    fetchExchange,
+  ],
+});
 ```
+
+9. Create the server side router which uses Grafast to execute queries:
+
+```typescript
 // app/serverRouter.tsx
 import { ssr } from "@carvajalconsultants/headstart/client";
 import { createRouter as createTanStackRouter } from "@tanstack/react-router";
@@ -91,6 +172,8 @@ import { Provider } from "urql";
 import { client } from "./graphql/serverProvider";
 import { routeTree } from "./routeTree.gen";
 
+import type { ReactNode } from "react";
+
 export function createRouter() {
 	const router = createTanStackRouter({
 		routeTree,
@@ -101,20 +184,21 @@ export function createRouter() {
 		// Send data to client so URQL can be hydrated.
 		dehydrate: () => ({ initialData: ssr.extractData() }),
 
-        // Wrap our entire route with the URQL provider so we can execute queries and mutations.
-		Wrap: ({ children }) => <Provider value={client}>{children}</Provider>,
+		// Wrap our entire route with the URQL provider so we can execute queries and mutations.
+		Wrap: ({ children }: { children: ReactNode }) => <Provider value={client}>{children}</Provider>,
 	});
 
 	return router;
 }
 ```
 
-9. Modify the TSR server-side rendering function to use this new router:
+10. Modify the TSR server-side rendering function to use this new router:
 
-```
+```typescript
+/* eslint-disable */
 // app/ssr.tsx
 /// <reference types="vinxi/types/server" />
-import { getRouterManifest } from "@tanstack/start/router-manifest";
+import { getRouterManifest } from "@tanstack/react-start/router-manifest";
 import {
 	createStartHandler,
 	defaultStreamHandler,
@@ -128,9 +212,9 @@ export default createStartHandler({
 })(defaultStreamHandler);
 ```
 
-10. Add the client side router which uses the fetch exchange to execute queries, mutations, etc.:
+11. Add the client side router which uses the fetch exchange to execute queries, mutations, etc.:
 
-```
+```typescript
 // app/clientRouter.tsx
 import { ssr } from "@carvajalconsultants/headstart/client";
 import { createRouter as createTanStackRouter } from "@tanstack/react-router";
@@ -138,6 +222,9 @@ import { Provider } from "urql";
 import { client } from "./graphql/clientProvider";
 import { routeTree } from "./routeTree.gen";
 
+import type { ReactNode } from "react";
+import type { SSRData } from "urql";
+
 export function createRouter() {
 	const router = createTanStackRouter({
 		routeTree,
@@ -146,20 +233,20 @@ export function createRouter() {
 		},
 		hydrate: (dehydrated) => {
 			// Hydrate URQL with data passed by TSR, this is generated by dehydrate function in server router.
-			ssr.restoreData(dehydrated.initialData);
+			ssr.restoreData(dehydrated.initialData as SSRData);
 		},
 
-        // Wrap our entire route with the URQL provider so we can execute queries and mutations.
-		Wrap: ({ children }) => <Provider value={client}>{children}</Provider>,
+		// Wrap our entire route with the URQL provider so we can execute queries and mutations.
+		Wrap: ({ children }: { children: ReactNode }) => <Provider value={client}>{children}</Provider>,
 	});
 
 	return router;
 }
 ```
 
-11. Tell TSR to use our client side router:
+12. Tell TSR to use our client side router:
 
-```
+```typescript
 // app/client.tsx
 /// <reference types="vinxi/types/client" />
 import { StartClient } from "@tanstack/start";
@@ -171,9 +258,9 @@ const router = createRouter();
 hydrateRoot(document.getElementById("root")!, <StartClient router={router} />);
 ```
 
-12. Last but not least, you're ready to start using URQL on your components and pages. First we create the route using the loader option so we can pre-load data:
+13. Last but not least, you're ready to start using URQL on your components and pages. First we create the route using the loader option so we can pre-load data:
 
-```
+```typescript
 export const Route = createFileRoute("/")({
 	...
 	validateSearch: zodSearchValidator(paramSchema),
@@ -188,9 +275,9 @@ export const Route = createFileRoute("/")({
 });
 ```
 
-13. Now in your component, you can query with URQL as you normally would:
+14. Now in your component, you can query with URQL as you normally would:
 
-```
+```typescript
 const Home = () => {
 	const { page } = Route.useSearch();
 
@@ -209,8 +296,8 @@ const Home = () => {
 
 ## Deployment
 
-1. Run `bun run build`
+1. Run `yarn run build`
 2. `cd .output/server`
 3. `rm -rf node_modules`
-4. `bun install`
-5. `bun run index.mjs`
+4. `yarn install`
+5. `yarn run index.mjs`

package/cookies.ts

@@ -0,0 +1,86 @@
+import Cookies from "js-cookie";
+
+import { getServerCookie, setServerCookie } from "./serverCookies";
+
+import type { CookieSetOptions } from "./serverCookies";
+
+/**
+ * Retrieves a cookie value by its name, working seamlessly in both client and server environments.
+ * This is crucial for applications that need to maintain state or user preferences across page loads
+ * and server-side rendering scenarios.
+ *
+ * @param name - The unique identifier of the cookie you want to retrieve (e.g., 'user_session', 'theme_preference')
+ * @returns The value stored in the cookie if it exists, or undefined if the cookie is not found
+ *
+ * @example
+ * // Get user's theme preference
+ * const theme = getCookie('theme_preference');
+ * if (theme === 'dark') {
+ *   // Apply dark theme
+ * }
+ */
+export const getCookie = async (name: string): Promise<string | undefined> => {
+  // Check if code is running in browser
+  if (typeof window !== "undefined") {
+    // Client-side cookie retrieval
+    return Cookies.get(name);
+  }
+
+  // Server-side cookie retrieval
+  return getServerCookie(name);
+};
+
+/**
+ * Sets a cookie with the specified name, value, and optional configuration parameters.
+ * Essential for storing user preferences, session tokens, or any client-side state that
+ * needs to persist across page reloads or browser sessions.
+ *
+ * @param name - The unique identifier for the cookie (e.g., 'auth_token', 'language_preference')
+ * @param value - The data to be stored in the cookie
+ * @param options - Configuration object for the cookie
+ * @param options.domain - Specifies which domains can access the cookie
+ * @param options.expires - When the cookie should expire, either as a Date object or days from now
+ * @param options.secure - If true, cookie will only be transmitted over HTTPS
+ * @param options.sameSite - Controls how the cookie behaves with cross-site requests
+ * @param options.path - The path on the server the cookie is valid for
+ *
+ * @example
+ * // Set a session cookie that expires in 7 days
+ * setCookie('session_id', 'abc123', {
+ *   expires: 7,
+ *   secure: true,
+ *   sameSite: 'strict'
+ * });
+ */
+export const setCookie = async (name: string, value: string, options?: CookieSetOptions) => {
+  if (typeof window !== "undefined") {
+    // Set cookie on the client side without hitting the server
+    Cookies.set(name, value, options);
+
+    return;
+  }
+
+  // Set cookie on the server side
+  await setServerCookie(name, value, options);
+};
+
+/**
+ * Removes a cookie from the browser, effectively logging out users or clearing stored preferences.
+ * Useful for scenarios like user logout, clearing cached data, or resetting user preferences.
+ *
+ * @param name - The name of the cookie to remove (e.g., 'auth_token', 'user_session')
+ *
+ * @example
+ * // Clear user session during logout
+ * removeCookie('auth_token');
+ * removeCookie('user_preferences');
+ */
+export const removeCookie = async (name: string) => {
+  if (typeof window !== "undefined") {
+    // Remove cookie on the client side without hitting the server
+    return Cookies.remove(name);
+  }
+
+  // Remove cookie on the server side
+  return setCookie(name, "", { expires: new Date(0) });
+};

package/grafastExchange.ts

@@ -6,9 +6,18 @@ import {
 	type OperationResult,
 } from "urql";
 import { filter, fromPromise, mergeMap, pipe } from "wonka";
+import type { App, H3Event } from "h3";
+import {
+  getQuery,
+  getRequestHeaders,
+  getRequestProtocol,
+  readRawBody,
+} from "h3";
 
 import type { Maybe } from "grafast";
 import type { PostGraphileInstance } from "postgraphile";
+import { getEvent, getWebRequest } from "vinxi/http";
+import { GrafservBodyBuffer, normalizeRequest, processHeaders, RequestDigest } from "postgraphile/grafserv";
 
 export const grafastExchange = (pgl: PostGraphileInstance): Exchange => {
 	return () => (ops$) => {
@@ -16,13 +25,49 @@ export const grafastExchange = (pgl: PostGraphileInstance): Exchange => {
 			ops$,
 
 			// Skip anything that's not a query since that's all we can run
-			filter((operation) => operation.kind === "query"),
+			filter((operation) => operation.kind === "query" || operation.kind === "mutation"),
 
 			mergeMap((operation) => fromPromise(runGrafastQuery(pgl, operation))),
 		);
 	};
 };
 
+/* This is a direct copy from: https://github.com/graphile/crystal/blob/main/grafast/grafserv/src/servers/h3/v1/index.ts#L24 */
+function getDigest(event: H3Event): RequestDigest {
+  const req = event.node.req;
+  const res = event.node.res;
+  return {
+    httpVersionMajor: req.httpVersionMajor,
+    httpVersionMinor: req.httpVersionMinor,
+    isSecure: getRequestProtocol(event) === "https",
+    method: event.method,
+    path: event.path,
+    headers: processHeaders(getRequestHeaders(event)),
+    getQueryParams() {
+      return getQuery(event) as Record<string, string | string[]>;
+    },
+    async getBody() {
+      const buffer = await readRawBody(event, false);
+      if (!buffer) {
+        throw new Error("Failed to retrieve body from h3");
+      }
+      return {
+        type: "buffer",
+        buffer,
+      } as GrafservBodyBuffer;
+    },
+    requestContext: {
+      h3v1: {
+        event,
+      },
+      node: {
+        req,
+        res,
+      },
+    },
+  };
+}
+
 /**
  * Run the URQL query with Grafast, without making an HTTP request to ourselves (which is unnecessary overhead).
  *
@@ -37,16 +82,25 @@ const runGrafastQuery = async (
 	try {
 		const { variables: variableValues, query: document } = operation;
 
-		const args = {
-			resolvedPreset: pgl.getResolvedPreset(),
-			schema: await pgl.getSchema(),
+		const { schema, resolvedPreset } = await pgl.getSchemaResult();
+
+		// Request/H3 info so we can run with it
+		const event = await getEvent();
+		const http = normalizeRequest(getDigest(event));
+
+		// Add the Graphile context to our args so Grafast can run
+		const args = await hookArgs({
+			schema,
 			document,
 			variableValues: variableValues as Maybe<{
 				readonly [variable: string]: unknown;
 			}>,
-		};
-		// Add the Graphile context to our args so Grafast can run
-		await hookArgs(args);
+			resolvedPreset,
+			requestContext: {
+				...http.requestContext,
+				http,
+			}
+		});
 
 		// Run the query with Grafast, to get the result from PostgreSQL
 		const result = await execute(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carvajalconsultants/headstart",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Library to assist in integrating PostGraphile with Tanstack Start and URQL.",
   "license": "MIT",
   "author": "Miguel Carvajal <omar@carvajalonline.com>",
@@ -9,9 +9,11 @@
   "main": "server.ts",
   "files": [
     "client.ts",
+    "cookies.ts",
     "grafastExchange.ts",
     "graphQLRouteHandler.ts",
-    "server.ts"
+    "server.ts",
+    "serverCookies.ts"
   ],
   "scripts": {
     "lint": "biome check --write"

package/serverCookies.ts

@@ -0,0 +1,160 @@
+export interface CookieSetOptions {
+  /**
+   * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
+   * domain is set, and most clients will consider the cookie to apply to only
+   * the current domain.
+   */
+  domain?: string | undefined;
+  /**
+   * Specifies a function that will be used to encode a cookie's value. Since
+   * value of a cookie has a limited character set (and must be a simple
+   * string), this function can be used to encode a value into a string suited
+   * for a cookie's value.
+   *
+   * The default function is the global `encodeURIComponent`, which will
+   * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
+   * any that fall outside of the cookie range.
+   */
+  encode?(value: string): string;
+  /**
+   * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
+   * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
+   * it on a condition like exiting a web browser application.
+   *
+   * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+   * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+   * possible not all clients by obey this, so if both are set, they should
+   * point to the same date and time.
+   */
+  expires?: Date | number | undefined;
+  /**
+   * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
+   * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
+   * default, the `HttpOnly` attribute is not set.
+   *
+   * *Note* be careful when setting this to true, as compliant clients will
+   * not allow client-side JavaScript to see the cookie in `document.cookie`.
+   */
+  httpOnly?: boolean | undefined;
+  /**
+   * Specifies the number (in seconds) to be the value for the `Max-Age`
+   * `Set-Cookie` attribute. The given number will be converted to an integer
+   * by rounding down. By default, no maximum age is set.
+   *
+   * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+   * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+   * possible not all clients by obey this, so if both are set, they should
+   * point to the same date and time.
+   */
+  maxAge?: number | undefined;
+  /**
+   * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
+   * By default, the path is considered the "default path".
+   */
+  path?: string | undefined;
+  /**
+   * Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
+   *
+   * - `'low'` will set the `Priority` attribute to `Low`.
+   * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+   * - `'high'` will set the `Priority` attribute to `High`.
+   *
+   * More information about the different priority levels can be found in
+   * [the specification][rfc-west-cookie-priority-00-4.1].
+   *
+   * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+   * This also means many clients may ignore this attribute until they understand it.
+   */
+  priority?: "low" | "medium" | "high" | undefined;
+  /**
+   * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
+   *
+   * - `true` will set the `SameSite` attribute to `Strict` for strict same
+   * site enforcement.
+   * - `false` will not set the `SameSite` attribute.
+   * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
+   * enforcement.
+   * - `'strict'` will set the `SameSite` attribute to Strict for strict same
+   * site enforcement.
+   *  - `'none'` will set the SameSite attribute to None for an explicit
+   *  cross-site cookie.
+   *
+   * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
+   *
+   * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
+   */
+  sameSite?: "lax" | "strict" | "none" | undefined;
+  /**
+   * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
+   * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
+   *
+   * *Note* be careful when setting this to `true`, as compliant clients will
+   * not send the cookie back to the server in the future if the browser does
+   * not have an HTTPS connection.
+   */
+  secure?: boolean | undefined;
+  /**
+   * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1)
+   * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
+   * `Partitioned` attribute is not set.
+   *
+   * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+   * This also means many clients may ignore this attribute until they understand it.
+   *
+   * More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
+   */
+  partitioned?: boolean;
+}
+
+/**
+ * Retrieves a cookie value during server-side rendering (SSR)
+ * This is useful when you need to access cookies that were set by the server
+ * before the page is sent to the client, such as authentication tokens or user preferences
+ *
+ * @param name - The name of the cookie to retrieve
+ * @returns The cookie value if running on the server, undefined if on the client
+ */
+export const getServerCookie = async (name: string) => {
+  // Only execute this logic during server-side rendering: https://v3.vitejs.dev/guide/ssr.html#conditional-logic
+  if (import.meta.env.SSR) {
+    // Dynamically import the cookie getter to avoid loading it on the client bundle
+    const { getCookie } = await import("@tanstack/react-start-server");
+
+    return getCookie(name);
+  }
+
+  return undefined;
+};
+
+/**
+ * Sets a cookie during server-side rendering (SSR)
+ * This is essential for scenarios where you need to set cookies before the initial page load,
+ * such as storing session tokens, user preferences, or other server-determined values
+ *
+ * @param name - The name of the cookie to set
+ * @param value - The value to store in the cookie
+ * @param options - Cookie configuration options
+ * @param options.expires - Expiration date or time in days from now
+ * @param options.path - Path where the cookie is valid
+ * @param options.domain - Domain where the cookie is valid
+ * @param options.secure - Whether the cookie should only be transmitted over HTTPS
+ * @param options.httpOnly - Whether the cookie should be inaccessible to JavaScript
+ * @param options.sameSite - Controls how the cookie behaves with cross-site requests
+ */
+export const setServerCookie = async (name: string, value: string, options?: CookieSetOptions) => {
+  // Only execute this logic during server-side rendering: https://v3.vitejs.dev/guide/ssr.html#conditional-logic
+  if (import.meta.env.SSR) {
+    // Dynamically import the cookie setter to avoid loading it on the client bundle
+    const { setCookie: setStartCookie } = await import("@tanstack/react-start-server");
+
+    // Set the cookie with provided options, converting numeric expiry to actual date
+    // This handles both relative (days from now) and absolute date expiration times
+    setStartCookie(name, value, {
+      ...options,
+      expires:
+        typeof options?.expires === "number"
+          ? new Date(Date.now() + options.expires * 864e5) // Convert days to milliseconds (864e5 = 24 * 60 * 60 * 1000)
+          : options?.expires,
+    });
+  }
+};