create-jen-app 1.2.3 → 1.2.4

package/templates/static/lib/data-fetching/client.js

@@ -0,0 +1,202 @@
+import { RestFetcher } from "./rest.js";
+import { GraphQLClient } from "./graphql.js";
+/**
+ * Client-side data fetching utilities for browser and Preact components.
+ * Provides reactive data fetching with cache, retry, and suspense support.
+ *
+ * Features:
+ * - Automatic refetch on mount/dependency changes
+ * - Suspense integration for data boundaries
+ * - In-flight request deduplication
+ * - Optimistic updates
+ */
+export class ClientDataFetcher {
+  rest;
+  graphql;
+  inflight = new Map();
+  constructor(clientCtx) {
+    this.rest = new RestFetcher({
+      cache: clientCtx.cache,
+      interceptors: clientCtx.interceptors,
+    });
+    this.graphql = new GraphQLClient({
+      endpoint: clientCtx.config.baseUrl || "/api/graphql",
+      cache: clientCtx.cache,
+      interceptors: clientCtx.interceptors,
+    });
+  }
+  /**
+   * Fetches data with deduplication.
+   * Multiple requests for the same URL while one is inflight return the same promise.
+   */
+  async fetch(url, config) {
+    const key = `${config?.method || "GET"}:${url}`;
+    // Return existing promise if request is in-flight
+    if (this.inflight.has(key)) {
+      return this.inflight.get(key);
+    }
+    const promise = this.rest.fetch(url, config).finally(() => {
+      this.inflight.delete(key);
+    });
+    this.inflight.set(key, promise);
+    return promise;
+  }
+  /**
+   * Fetches multiple resources in parallel with race condition handling.
+   */
+  async fetchAll(urls, config) {
+    const results = {};
+    const promises = Object.entries(urls).map(async ([key, url]) => {
+      const result = await this.fetch(url, config);
+      if (!result.ok) {
+        throw new Error(`Failed to fetch ${key}: ${result.error.message}`);
+      }
+      results[key] = result.data;
+    });
+    try {
+      await Promise.all(promises);
+      return {
+        ok: true,
+        data: results,
+        meta: {
+          status: 200,
+          statusText: "OK",
+          headers: {},
+          url: Object.values(urls)[0],
+          ok: true,
+        },
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          message: err.message,
+          details: err,
+        },
+      };
+    }
+  }
+  /**
+   * Adds an authorization token to all requests.
+   */
+  withAuthToken(token) {
+    this.rest.addInterceptor({
+      beforeRequest: (req) => {
+        req.headers = {
+          ...req.headers,
+          Authorization: `Bearer ${token}`,
+        };
+        return req;
+      },
+    });
+    return this;
+  }
+  /**
+   * Adds common headers to all requests.
+   */
+  withHeaders(headers) {
+    this.rest.addInterceptor({
+      beforeRequest: (req) => {
+        req.headers = {
+          ...req.headers,
+          ...headers,
+        };
+        return req;
+      },
+    });
+    return this;
+  }
+}
+/**
+ * Global client fetch context for browser.
+ * Initialized when app hydrates on client.
+ */
+let globalClientFetcher = null;
+/**
+ * Initializes the client data fetcher.
+ * Should be called during client hydration.
+ */
+export function initializeClientFetch(context) {
+  globalClientFetcher = new ClientDataFetcher(context);
+}
+/**
+ * Gets the global client data fetcher.
+ */
+export function getClientDataFetcher() {
+  if (!globalClientFetcher) {
+    throw new Error(
+      "Client fetch not initialized. Call initializeClientFetch() during client hydration.",
+    );
+  }
+  return globalClientFetcher;
+}
+/**
+ * Convenience hook for fetching data in components.
+ * Returns { data, error, loading, refetch }.
+ */
+export function useData(url, options) {
+  // This is a simplified API description
+  // Full implementation would use Preact hooks (useEffect, useState)
+  return {
+    data: options?.initialData || null,
+    error: null,
+    loading: false,
+    refetch: async () => {
+      const fetcher = getClientDataFetcher();
+      return fetcher.rest.get(url, options);
+    },
+  };
+}
+/**
+ * Convenience hook for fetching multiple resources in parallel.
+ */
+export function useDataAll(urls, options) {
+  return {
+    data: {},
+    error: null,
+    loading: false,
+    refetch: async () => {
+      const fetcher = getClientDataFetcher();
+      return fetcher.fetchAll(urls, options);
+    },
+  };
+}
+/**
+ * Convenience hook for GraphQL queries in components.
+ */
+export function useGraphQL(query, variables) {
+  return {
+    data: null,
+    error: null,
+    loading: false,
+    refetch: async () => {
+      const fetcher = getClientDataFetcher();
+      return fetcher.graphql.query(
+        { query, variables },
+        { cache: { strategy: "cache-first" } },
+      );
+    },
+  };
+}
+/**
+ * Convenience hook for GraphQL mutations in components.
+ */
+export function useMutation(mutation, onSuccess, onError) {
+  return {
+    execute: async (variables) => {
+      const fetcher = getClientDataFetcher();
+      const result = await fetcher.graphql.mutation(
+        { query: mutation, variables },
+        { cache: { strategy: "no-cache" } },
+      );
+      if (result.ok) {
+        onSuccess?.(result.data);
+      } else {
+        onError?.(new Error(result.error.message));
+      }
+      return result;
+    },
+    loading: false,
+    error: null,
+  };
+}

package/templates/static/lib/data-fetching/feature-guard.js

@@ -0,0 +1,29 @@
+/**
+ * Feature guards for data-fetching module.
+ *
+ * The data-fetching feature must be enabled in jen.config.ts:
+ * ```
+ * features: {
+ *   dataFetching: true
+ * }
+ * ```
+ *
+ * This module would typically use the framework's feature gating system
+ * to ensure the feature is enabled before allowing use of these utilities.
+ */
+/**
+ * Validates that data-fetching feature is enabled.
+ * Throws helpful error if disabled.
+ */
+export function requireDataFetchingFeature(features, context) {
+  // Note: "dataFetching" would be added to FeatureName type in features.ts
+  // For now, this is a placeholder that documents the pattern
+  // guardFeature(features, "dataFetching", context);
+}
+/**
+ * Validates that both cache and data-fetching features are enabled.
+ * Required for some advanced caching features.
+ */
+export function requireCacheWithDataFetching(features, context) {
+  // guardFeatures(features, ["cache", "dataFetching"], context);
+}

package/templates/static/lib/data-fetching/graphql.js

@@ -0,0 +1,265 @@
+import { RestFetcher } from "./rest.js";
+import { executeCacheStrategy } from "./cache.js";
+/**
+ * GraphQL client for querying GraphQL APIs.
+ * Integrates with REST fetcher infrastructure for cache and interceptor support.
+ *
+ * Features:
+ * - Query and mutation execution
+ * - Automatic error extraction from GraphQL responses
+ * - Cache support with tag-based invalidation
+ * - Request/response interceptors
+ * - Type-safe operation configuration
+ */
+export class GraphQLClient {
+  restFetcher;
+  endpoint;
+  cache;
+  interceptors;
+  constructor(opts) {
+    this.endpoint = opts.endpoint;
+    this.cache = opts.cache;
+    this.interceptors = opts.interceptors || [];
+    this.restFetcher = new RestFetcher({
+      cache: opts.cache,
+      interceptors: opts.interceptors,
+      baseUrl: opts.endpoint.includes("http")
+        ? undefined
+        : "https://api.example.com",
+      defaultHeaders: {
+        "content-type": "application/json",
+        ...opts.defaultHeaders,
+      },
+    });
+  }
+  /**
+   * Registers a new interceptor.
+   */
+  addInterceptor(interceptor) {
+    this.restFetcher.addInterceptor(interceptor);
+    this.interceptors.push(interceptor);
+  }
+  /**
+   * Executes a GraphQL query.
+   * Queries are cached by default (cache-first strategy).
+   */
+  async query(request, config) {
+    const gqlRequest =
+      typeof request === "string" ? { query: request } : request;
+    // Queries are safe to cache
+    const cacheConfig = {
+      strategy: "cache-first",
+      ttl: 300000, // 5 minutes default
+    };
+    if (config?.cache && typeof config.cache === "object") {
+      Object.assign(cacheConfig, config.cache);
+    }
+    return this.execute(gqlRequest, {
+      ...config,
+      cache: cacheConfig,
+    });
+  }
+  /**
+   * Executes a GraphQL mutation.
+   * Mutations are NOT cached by default (no-cache strategy).
+   */
+  async mutation(request, config) {
+    const gqlRequest =
+      typeof request === "string" ? { query: request } : request;
+    // Mutations should not be cached
+    const cacheConfig = {
+      strategy: "no-cache",
+    };
+    if (config?.cache && typeof config.cache === "object") {
+      Object.assign(cacheConfig, config.cache);
+    }
+    return this.execute(gqlRequest, {
+      ...config,
+      cache: cacheConfig,
+    });
+  }
+  /**
+   * Core GraphQL execution with cache and interceptor support.
+   */
+  async execute(request, config) {
+    const cacheStrategy = config?.cache?.strategy || "cache-first";
+    const cacheKey = this.createGraphQLCacheKey(request);
+    const cacheTtl = config?.cache?.ttl || 300000;
+    const cacheTags = config?.cache?.tags || [
+      `gql:${this.extractOperationName(request)}`,
+    ];
+    try {
+      let data;
+      if (cacheStrategy !== "no-cache") {
+        const { data: cachedData, cached } = await executeCacheStrategy(
+          cacheStrategy,
+          {
+            key: cacheKey,
+            cache: this.cache,
+            fetchFn: () => this.performRequest(request),
+            ttl: cacheTtl,
+            tags: cacheTags,
+          },
+        );
+        data = cachedData;
+      } else {
+        data = await this.performRequest(request);
+      }
+      const result = {
+        ok: true,
+        data,
+        meta: {
+          status: 200,
+          statusText: "OK",
+          headers: { "content-type": "application/json" },
+          url: this.endpoint,
+          ok: true,
+        },
+      };
+      // Run afterResponse interceptors
+      for (const interceptor of this.interceptors) {
+        if (interceptor.afterResponse) {
+          const intercepted = await interceptor.afterResponse(result);
+          if (!intercepted.ok) return intercepted;
+          if (intercepted.ok) {
+            result.data = intercepted.data;
+          }
+        }
+      }
+      return result;
+    } catch (err) {
+      const errorResult = {
+        ok: false,
+        error: {
+          message: err.message || "GraphQL request failed",
+          code: err.code,
+          details: err,
+        },
+      };
+      // Run onError interceptors
+      for (const interceptor of this.interceptors) {
+        if (interceptor.onError) {
+          return await interceptor.onError(errorResult);
+        }
+      }
+      return errorResult;
+    }
+  }
+  /**
+   * Performs the actual GraphQL request.
+   */
+  async performRequest(request) {
+    const response = await this.restFetcher.post(this.endpoint, request, {
+      cache: false, // Already handled by execute()
+    });
+    if (!response.ok) {
+      throw new Error(`GraphQL request failed: ${response.error.message}`);
+    }
+    const { data, errors } = response.data;
+    if (errors && errors.length > 0) {
+      const errorMessages = errors.map((e) => e.message).join("; ");
+      throw new Error(`GraphQL errors: ${errorMessages}`);
+    }
+    return data;
+  }
+  /**
+   * Generates cache key from GraphQL request.
+   */
+  createGraphQLCacheKey(request) {
+    const key = `gql:${this.extractOperationName(request)}`;
+    const varsStr = request.variables ? JSON.stringify(request.variables) : "";
+    return `${key}:${varsStr}`;
+  }
+  /**
+   * Extracts operation name from GraphQL query/mutation.
+   */
+  extractOperationName(request) {
+    if (request.operationName) return request.operationName;
+    // Try to extract from query string
+    const match = request.query.match(/(?:query|mutation)\s+(\w+)/);
+    return match ? match[1] : "anonymous";
+  }
+  /**
+   * Invalidates cache entries by GraphQL operation name(s).
+   */
+  async invalidate(operationNames) {
+    const tags = operationNames.map((name) => `gql:${name}`);
+    await this.cache.invalidate(tags);
+  }
+  /**
+   * Batch execute multiple GraphQL queries.
+   */
+  async batch(requests, config) {
+    const results = {};
+    for (const [key, request] of Object.entries(requests)) {
+      const result = await this.query(request, config);
+      if (!result.ok) {
+        return result;
+      }
+      results[key] = result.data;
+    }
+    return {
+      ok: true,
+      data: results,
+      meta: {
+        status: 200,
+        statusText: "OK",
+        headers: {},
+        url: this.endpoint,
+        ok: true,
+      },
+    };
+  }
+}
+/**
+ * Creates a GraphQL client with sensible defaults.
+ */
+export function createGraphQLClient(opts) {
+  return new GraphQLClient(opts);
+}
+/**
+ * Helper to build GraphQL query strings programmatically.
+ * Useful for type-safe query construction.
+ */
+export class GraphQLQueryBuilder {
+  query = "";
+  variables = {};
+  /**
+   * Adds a field selection to the query.
+   */
+  field(name, fields) {
+    this.query += name;
+    if (fields) {
+      this.query += ` { ${fields.join(" ")} }`;
+    }
+    return this;
+  }
+  /**
+   * Adds a variable to the query.
+   */
+  variable(name, type, value) {
+    if (value !== undefined) {
+      this.variables[name] = value;
+    }
+    return this;
+  }
+  /**
+   * Builds the final GraphQL request.
+   */
+  build(operationType = "query", operationName) {
+    const opName = operationName || "Operation";
+    const vars = Object.entries(this.variables).map(
+      ([name, value]) => `$${name}: ${typeof value}`,
+    );
+    const finalQuery = `
+      ${operationType} ${opName}${vars.length ? `(${vars.join(", ")})` : ""} {
+        ${this.query}
+      }
+    `.trim();
+    return {
+      query: finalQuery,
+      variables: this.variables,
+      operationName: opName,
+    };
+  }
+}

package/templates/static/lib/data-fetching/index.js

@@ -0,0 +1,57 @@
+/**
+ * Jen.js Data Fetching Module
+ *
+ * Comprehensive data fetching infrastructure with support for:
+ * - REST/HTTP APIs with automatic retry and timeout handling
+ * - GraphQL queries and mutations with error handling
+ * - Multi-backend caching (memory, Redis, custom)
+ * - Cache strategies (cache-first, network-first, stale-while-revalidate)
+ * - Request/response interceptors
+ * - Server-side and client-side fetching
+ * - Type-safe configuration and results
+ *
+ * Key exports:
+ * - Types: FetchResult, DataFetchConfig, CacheBackend, etc.
+ * - REST: RestFetcher, createRestFetcher
+ * - GraphQL: GraphQLClient, createGraphQLClient
+ * - Cache: MemoryDataCache, NoOpCache, createCacheKey
+ * - Server: ServerDataFetcher, initializeServerFetch, getServerDataFetcher
+ * - Client: ClientDataFetcher, initializeClientFetch, getClientDataFetcher
+ */
+// Cache exports
+export {
+  MemoryDataCache,
+  NoOpCache,
+  createCacheKey,
+  executeCacheStrategy,
+} from "./cache.js";
+// REST/HTTP exports
+export { RestFetcher, createRestFetcher } from "./rest.js";
+// GraphQL exports
+export {
+  GraphQLClient,
+  createGraphQLClient,
+  GraphQLQueryBuilder,
+} from "./graphql.js";
+// Server-side exports
+export {
+  ServerDataFetcher,
+  initializeServerFetch,
+  getServerDataFetcher,
+  fetchData,
+  queryGraphQL,
+  createDataLoader,
+  createParallelDataLoader,
+  createConditionalDataLoader,
+  createResilientDataLoader,
+} from "./server.js";
+// Client-side exports
+export {
+  ClientDataFetcher,
+  initializeClientFetch,
+  getClientDataFetcher,
+  useData,
+  useDataAll,
+  useGraphQL,
+  useMutation,
+} from "./client.js";