create-jen-app 1.2.2 → 1.2.4

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

@@ -0,0 +1,223 @@
+/**
+ * In-memory cache implementation for data fetching.
+ * Supports TTL-based expiration and tag-based invalidation.
+ * Suitable for development and single-process deployments.
+ */
+export class MemoryDataCache {
+  store = new Map();
+  tags = new Map();
+  /**
+   * Retrieves a cached value by key.
+   * Returns null if key doesn't exist or entry has expired.
+   */
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    // Check expiration
+    const now = Date.now();
+    if (now - entry.timestamp > entry.ttl) {
+      this.store.delete(key);
+      this.cleanupTags(key);
+      return null;
+    }
+    return entry.data;
+  }
+  /**
+   * Stores a value in cache with optional TTL and tags.
+   */
+  async set(
+    key,
+    value,
+    ttl = 60000, // 1 minute default
+    tags,
+  ) {
+    const entry = {
+      data: value,
+      timestamp: Date.now(),
+      ttl,
+      tags,
+    };
+    this.store.set(key, entry);
+    // Register tags for invalidation
+    if (tags) {
+      for (const tag of tags) {
+        if (!this.tags.has(tag)) {
+          this.tags.set(tag, new Set());
+        }
+        this.tags.get(tag).add(key);
+      }
+    }
+  }
+  /**
+   * Deletes a specific cache entry.
+   */
+  async delete(key) {
+    this.store.delete(key);
+    this.cleanupTags(key);
+  }
+  /**
+   * Clears all cache entries.
+   */
+  async clear() {
+    this.store.clear();
+    this.tags.clear();
+  }
+  /**
+   * Invalidates all cache entries with specified tags.
+   * Useful for mass cache busting after data mutations.
+   */
+  async invalidate(tags) {
+    const keysToDelete = new Set();
+    for (const tag of tags) {
+      const keys = this.tags.get(tag);
+      if (keys) {
+        for (const key of keys) {
+          keysToDelete.add(key);
+        }
+      }
+    }
+    for (const key of keysToDelete) {
+      this.store.delete(key);
+    }
+    // Clean up tag mappings
+    for (const tag of tags) {
+      this.tags.delete(tag);
+    }
+  }
+  /**
+   * Internal helper to clean up tag references when a key is deleted.
+   */
+  cleanupTags(key) {
+    for (const keySet of this.tags.values()) {
+      keySet.delete(key);
+    }
+  }
+  /**
+   * Returns cache statistics for debugging.
+   */
+  getStats() {
+    return {
+      size: this.store.size,
+      tags: this.tags.size,
+      memory: this.estimateMemory(),
+    };
+  }
+  /**
+   * Rough estimate of memory usage (for monitoring).
+   */
+  estimateMemory() {
+    let bytes = 0;
+    for (const [key, entry] of this.store) {
+      bytes += key.length * 2; // Rough UTF-16 estimate
+      bytes += JSON.stringify(entry.data).length;
+    }
+    return bytes;
+  }
+}
+/**
+ * NoOp cache implementation that doesn't cache anything.
+ * Used when caching is disabled or for testing.
+ */
+export class NoOpCache {
+  async get() {
+    return null;
+  }
+  async set() {
+    // No-op
+  }
+  async delete() {
+    // No-op
+  }
+  async clear() {
+    // No-op
+  }
+  async invalidate() {
+    // No-op
+  }
+}
+/**
+ * Creates a cache key from a URL and optional parameters.
+ * Ensures consistent key generation across requests.
+ */
+export function createCacheKey(url, options) {
+  let key = url;
+  if (options?.method && options.method !== "GET") {
+    key += `|${options.method}`;
+  }
+  if (options?.body) {
+    const bodyStr =
+      typeof options.body === "string"
+        ? options.body
+        : JSON.stringify(options.body);
+    key += `|${hashString(bodyStr)}`;
+  }
+  if (options?.headers) {
+    const headerStr = JSON.stringify(options.headers);
+    key += `|${hashString(headerStr)}`;
+  }
+  return key;
+}
+/**
+ * Simple hash function for generating consistent cache keys.
+ */
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return Math.abs(hash).toString(36);
+}
+/**
+ * Cache strategy executor for handling different cache modes.
+ */
+export async function executeCacheStrategy(
+  strategy,
+  { key, cache, fetchFn, ttl = 60000, tags },
+) {
+  switch (strategy) {
+    case "cache-first": {
+      const cached = await cache.get(key);
+      if (cached !== null) {
+        return { data: cached, cached: true };
+      }
+      const fresh = await fetchFn();
+      await cache.set(key, fresh, ttl, tags);
+      return { data: fresh, cached: false };
+    }
+    case "network-first": {
+      try {
+        const fresh = await fetchFn();
+        await cache.set(key, fresh, ttl, tags);
+        return { data: fresh, cached: false };
+      } catch (error) {
+        const cached = await cache.get(key);
+        if (cached !== null) {
+          return { data: cached, cached: true };
+        }
+        throw error;
+      }
+    }
+    case "stale-while-revalidate": {
+      const cached = await cache.get(key);
+      // Return cached immediately, revalidate in background
+      if (cached !== null) {
+        fetchFn()
+          .then((fresh) => cache.set(key, fresh, ttl, tags))
+          .catch(() => {
+            /* Silently fail background revalidation */
+          });
+        return { data: cached, cached: true };
+      }
+      const fresh = await fetchFn();
+      await cache.set(key, fresh, ttl, tags);
+      return { data: fresh, cached: false };
+    }
+    case "no-cache":
+    default: {
+      const fresh = await fetchFn();
+      return { data: fresh, cached: false };
+    }
+  }
+}

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,
+    };
+  }
+}