@carvajalconsultants/headstart 1.0.4 → 1.0.5

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carvajalconsultants/headstart",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "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,
+    });
+  }
+};