create-jen-app 1.2.2 → 1.2.4

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";

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

@@ -0,0 +1,256 @@
+import { createCacheKey, executeCacheStrategy } from "./cache.js";
+/**
+ * Unified REST/HTTP data fetcher for both server and client.
+ * Integrates with cache, retry logic, interceptors, and timeout handling.
+ *
+ * Supports:
+ * - Multiple HTTP methods (GET, POST, PUT, DELETE, PATCH)
+ * - Request/response transformation via interceptors
+ * - Automatic retry with backoff strategies
+ * - Pluggable cache backends
+ * - Comprehensive error handling
+ */
+export class RestFetcher {
+  cache;
+  interceptors;
+  baseUrl;
+  defaultHeaders = {};
+  constructor(opts) {
+    this.cache = opts?.cache;
+    this.interceptors = opts?.interceptors || [];
+    this.baseUrl = opts?.baseUrl;
+    this.defaultHeaders = opts?.defaultHeaders || {};
+  }
+  /**
+   * Registers a new interceptor for request/response transformation.
+   */
+  addInterceptor(interceptor) {
+    this.interceptors.push(interceptor);
+  }
+  /**
+   * Performs a GET request with optional caching.
+   */
+  async get(url, config) {
+    return this.fetch(url, { ...config, method: "GET" });
+  }
+  /**
+   * Performs a POST request.
+   */
+  async post(url, body, config) {
+    return this.fetch(url, { ...config, method: "POST", body });
+  }
+  /**
+   * Performs a PUT request.
+   */
+  async put(url, body, config) {
+    return this.fetch(url, { ...config, method: "PUT", body });
+  }
+  /**
+   * Performs a DELETE request.
+   */
+  async delete(url, config) {
+    return this.fetch(url, { ...config, method: "DELETE" });
+  }
+  /**
+   * Performs a PATCH request.
+   */
+  async patch(url, body, config) {
+    return this.fetch(url, { ...config, method: "PATCH", body });
+  }
+  /**
+   * Core fetch method with cache, retry, and interceptor support.
+   */
+  async fetch(url, config) {
+    const fullUrl = this.resolveUrl(url);
+    const method = config?.method || "GET";
+    // Merge headers
+    const headers = {
+      ...this.defaultHeaders,
+      ...config?.headers,
+      ...(config?.body && !config.headers?.["content-type"]
+        ? { "content-type": "application/json" }
+        : {}),
+    };
+    let options = {
+      method,
+      headers,
+      body: config?.body,
+      timeout: config?.timeout || 30000,
+      credentials: config?.credentials || "same-origin",
+      signal: config?.signal,
+    };
+    // Run beforeRequest interceptors
+    for (const interceptor of this.interceptors) {
+      if (interceptor.beforeRequest) {
+        options = await interceptor.beforeRequest(options);
+      }
+    }
+    try {
+      // Check cache first if enabled
+      const cacheStrategy =
+        typeof config?.cache === "boolean"
+          ? config.cache
+            ? "cache-first"
+            : "no-cache"
+          : config?.cache?.strategy || "no-cache";
+      const cacheKey = createCacheKey(fullUrl, options);
+      const cacheTags =
+        (typeof config?.cache === "object" && config.cache.tags) || [];
+      const cacheTtl =
+        (typeof config?.cache === "object" && config.cache.ttl) || 60000;
+      let result;
+      if (cacheStrategy !== "no-cache" && method === "GET") {
+        const { data, cached } = await executeCacheStrategy(cacheStrategy, {
+          key: cacheKey,
+          cache: this.cache,
+          fetchFn: () => this.performFetch(fullUrl, options),
+          ttl: cacheTtl,
+          tags: cacheTags,
+        });
+        result = {
+          ok: true,
+          data,
+          meta: {
+            status: 200,
+            statusText: "OK",
+            headers: {},
+            url: fullUrl,
+            ok: true,
+            cached,
+          },
+        };
+      } else {
+        const data = await this.performFetch(fullUrl, options);
+        result = {
+          ok: true,
+          data,
+          meta: {
+            status: 200,
+            statusText: "OK",
+            headers: {},
+            url: fullUrl,
+            ok: true,
+            cached: false,
+          },
+        };
+      }
+      // Run afterResponse interceptors
+      for (const interceptor of this.interceptors) {
+        if (interceptor.afterResponse) {
+          result = await interceptor.afterResponse(result);
+        }
+      }
+      return result;
+    } catch (err) {
+      const errorResult = {
+        ok: false,
+        error: {
+          message: err.message || "Unknown error",
+          code: err.code,
+          status: err.status,
+          details: err,
+        },
+      };
+      // Run onError interceptors
+      for (const interceptor of this.interceptors) {
+        if (interceptor.onError) {
+          return await interceptor.onError(errorResult);
+        }
+      }
+      return errorResult;
+    }
+  }
+  /**
+   * Internal method to perform the actual HTTP request with retry logic.
+   */
+  async performFetch(url, options) {
+    const retryConfig = {
+      attempts: 3,
+      delay: 100,
+      backoff: "exponential",
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt < retryConfig.attempts; attempt++) {
+      try {
+        const response = await this.executeRequest(url, options);
+        return response;
+      } catch (err) {
+        lastError = err;
+        // Don't retry on client-side errors (4xx)
+        if (err.status && err.status >= 400 && err.status < 500) {
+          throw err;
+        }
+        // Calculate backoff delay
+        if (attempt < retryConfig.attempts - 1) {
+          const delay =
+            retryConfig.backoff === "exponential"
+              ? retryConfig.delay * Math.pow(2, attempt)
+              : retryConfig.delay * (attempt + 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastError || new Error("Failed to fetch after retries");
+  }
+  /**
+   * Executes the actual HTTP request using fetch API (universal).
+   */
+  async executeRequest(url, options) {
+    const fetchOpts = {
+      method: options.method,
+      headers: options.headers,
+      credentials: options.credentials,
+      signal: options.signal,
+    };
+    if (options.body) {
+      fetchOpts.body =
+        typeof options.body === "string"
+          ? options.body
+          : JSON.stringify(options.body);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      options.timeout || 30000,
+    );
+    try {
+      const response = await fetch(url, {
+        ...fetchOpts,
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        const error = new Error(
+          errorText || response.statusText || "HTTP Error",
+        );
+        error.status = response.status;
+        throw error;
+      }
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      } else if (contentType.includes("text")) {
+        return await response.text();
+      } else {
+        return await response.arrayBuffer();
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Resolves relative URLs using baseUrl if configured.
+   */
+  resolveUrl(url) {
+    if (this.baseUrl && !url.startsWith("http")) {
+      return this.baseUrl.replace(/\/$/, "") + "/" + url.replace(/^\//, "");
+    }
+    return url;
+  }
+}
+/**
+ * Creates a REST fetcher with sensible defaults.
+ */
+export function createRestFetcher(opts) {
+  return new RestFetcher(opts);
+}

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

@@ -0,0 +1,182 @@
+import { RestFetcher } from "./rest.js";
+import { GraphQLClient } from "./graphql.js";
+/**
+ * Server-side data fetching utilities for use in loaders and middleware.
+ * Provides access to REST and GraphQL clients with proper cache integration.
+ *
+ * Server fetchers have access to:
+ * - Backend cache (memory, Redis, etc.)
+ * - Request/response interceptors
+ * - Loader context (URL, params, headers, cookies)
+ */
+export class ServerDataFetcher {
+  rest;
+  graphql;
+  context;
+  constructor(serverCtx) {
+    this.rest = new RestFetcher({
+      cache: serverCtx.cache,
+      interceptors: serverCtx.interceptors,
+    });
+    this.graphql = new GraphQLClient({
+      endpoint: serverCtx.config.baseUrl || "https://api.example.com/graphql",
+      cache: serverCtx.cache,
+      interceptors: serverCtx.interceptors,
+    });
+    this.context = serverCtx.loaderContext;
+  }
+  /**
+   * Returns loader context information for conditional data fetching.
+   * Useful for customizing requests based on route params, headers, etc.
+   */
+  getLoaderContext() {
+    return this.context;
+  }
+  /**
+   * Creates a request interceptor that adds authentication headers.
+   * Common pattern for API authentication.
+   */
+  withAuthToken(token) {
+    this.rest.addInterceptor({
+      beforeRequest: (req) => {
+        req.headers = {
+          ...req.headers,
+          Authorization: `Bearer ${token}`,
+        };
+        return req;
+      },
+    });
+    return this;
+  }
+  /**
+   * Creates a request interceptor that adds common headers.
+   */
+  withHeaders(headers) {
+    this.rest.addInterceptor({
+      beforeRequest: (req) => {
+        req.headers = {
+          ...req.headers,
+          ...headers,
+        };
+        return req;
+      },
+    });
+    return this;
+  }
+  /**
+   * Adds request tracing/logging interceptor.
+   */
+  withLogging(logger) {
+    const log = logger || console.log;
+    this.rest.addInterceptor({
+      beforeRequest: (req) => {
+        log(`[ServerFetch] ${req.method} ${req.headers}`);
+        return req;
+      },
+      afterResponse: (res) => {
+        log(`[ServerFetch] Response: ${res.ok ? "ok" : "error"}`);
+        return res;
+      },
+    });
+    return this;
+  }
+}
+/**
+ * Global cache instance for server-side fetching.
+ * Should be initialized during app startup with the configured cache backend.
+ */
+let globalServerCache = null;
+/**
+ * Initializes the global server fetch context.
+ * Called during app startup to set up cache and interceptors.
+ */
+export function initializeServerFetch(context) {
+  globalServerCache = context;
+}
+/**
+ * Gets the server data fetcher for use in loaders and middleware.
+ * Must be called after initializeServerFetch().
+ */
+export function getServerDataFetcher(loaderCtx) {
+  if (!globalServerCache) {
+    throw new Error(
+      "Server fetch not initialized. Call initializeServerFetch() during app startup.",
+    );
+  }
+  return new ServerDataFetcher({
+    ...globalServerCache,
+    loaderContext: loaderCtx,
+  });
+}
+/**
+ * Convenience function for quick REST GET requests in loaders.
+ * Uses the global server fetch context.
+ */
+export async function fetchData(url, loaderCtx) {
+  const fetcher = getServerDataFetcher(loaderCtx);
+  return fetcher.rest.get(url);
+}
+/**
+ * Convenience function for GraphQL queries in loaders.
+ */
+export async function queryGraphQL(query, variables, loaderCtx) {
+  const fetcher = getServerDataFetcher(loaderCtx);
+  return fetcher.graphql.query({ query, variables });
+}
+/**
+ * Creates a data loader that wraps error handling and logging.
+ */
+export function createDataLoader(fn) {
+  return async (loaderCtx) => {
+    try {
+      const fetcher = getServerDataFetcher(loaderCtx);
+      return await fn(fetcher);
+    } catch (err) {
+      console.error("[DataLoader] Error:", err);
+      throw err;
+    }
+  };
+}
+/**
+ * Parallel data loader for fetching multiple resources concurrently.
+ */
+export function createParallelDataLoader(loaders) {
+  return async (loaderCtx) => {
+    const fetcher = getServerDataFetcher(loaderCtx);
+    const results = {};
+    const promises = Object.entries(loaders).map(async ([key, loader]) => {
+      try {
+        results[key] = await loader(loaderCtx);
+      } catch (err) {
+        console.error(`[DataLoader] ${String(key)} failed:`, err);
+        throw err;
+      }
+    });
+    await Promise.all(promises);
+    return results;
+  };
+}
+/**
+ * Conditional data loader that fetches based on route params or query.
+ */
+export function createConditionalDataLoader(condition, loader, fallback) {
+  return async (loaderCtx) => {
+    if (condition(loaderCtx)) {
+      return loader(loaderCtx);
+    }
+    return fallback;
+  };
+}
+/**
+ * Error-tolerant data loader with fallback value.
+ */
+export function createResilientDataLoader(loader, fallback) {
+  return async (loaderCtx) => {
+    try {
+      return await loader(loaderCtx);
+    } catch (err) {
+      console.warn("[DataLoader] Using fallback due to error:", err);
+      return fallback;
+    }
+  };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Core types for the data fetching system.
+ * Supports REST, GraphQL, and custom fetch operations with caching.
+ */
+export {};

package/templates/static/lib/db/connector.js

@@ -1,33 +1,42 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { JDBDriver } from "./drivers/jdb";
 import { SQLDriver } from "./drivers/sql";
+/**
+ * Factory class for creating database driver instances.
+ * The DBConnector uses the factory pattern to instantiate the appropriate driver
+ * based on the configured database type. This allows the application to support
+ * multiple database backends without tight coupling to any single implementation.
+ *
+ * Supported database types:
+ * - jdb: Embedded JSON database (built-in, no external dependencies)
+ * - sqlite: SQLite relational database
+ * - postgres: PostgreSQL relational database
+ * - mysql: MySQL relational database
+ */
 export class DBConnector {
-    static create(config) {
-        switch (config.type) {
-            case "jdb":
-                return new JDBDriver(config);
-            case "sqlite":
-            case "postgres":
-            case "mysql":
-                return new SQLDriver(config);
-            default:
-                throw new Error(`Unsupported DB type: ${config.type}`);
-        }
+  /**
+   * Creates and returns a database driver instance based on the configuration.
+   * The driver implements the IDBDriver interface and provides the same API
+   * regardless of the underlying database type.
+   *
+   * @param config The database configuration including type and connection parameters.
+   * @returns An IDBDriver instance for the specified database type.
+   * @throws Error if the configured database type is not supported.
+   *
+   * @example
+   * const config: DBConfig = { type: 'sqlite', path: './data.db' };
+   * const driver = DBConnector.create(config);
+   * const records = await driver.query('SELECT * FROM users');
+   */
+  static create(config) {
+    switch (config.type) {
+      case "jdb":
+        return new JDBDriver(config);
+      case "sqlite":
+      case "postgres":
+      case "mysql":
+        return new SQLDriver(config);
+      default:
+        throw new Error(`Unsupported DB type: ${config.type}`);
     }
+  }
 }

package/templates/static/lib/db/drivers/jdb.js

@@ -1,59 +1,44 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { JDBEngine } from "../../jdb";
 export class JDBDriver {
-    engine;
-    constructor(config) {
-        const jdbConfig = config.jdb || {
-            root: "./data",
-            inMemory: false,
-        };
-        this.engine = new JDBEngine(jdbConfig);
-    }
-    async connect() {
-        await this.engine.connect();
-    }
-    async disconnect() {
-        await this.engine.disconnect();
-    }
-    async query(q) {
-        if (typeof q === "string") {
-            throw new Error("Raw string queries not supported in JDB directly. Use object syntax.");
-        }
-        if ("sql" in q) {
-            throw new Error("SQL queries not supported in JDB driver.");
-        }
-        const query = q;
-        const coll = this.engine.collection(query.find);
-        return await coll.find(query.where || {}, query.options);
-    }
-    async create(collection, data) {
-        return await this.engine.collection(collection).insert(data);
-    }
-    async update(collection, filter, update) {
-        return await this.engine
-            .collection(collection)
-            .update(filter, update, true);
-    }
-    async delete(collection, filter) {
-        return await this.engine.collection(collection).delete(filter, true);
-    }
-    async count(collection, filter) {
-        return await this.engine.collection(collection).count(filter);
-    }
+  engine;
+  constructor(config) {
+    const jdbConfig = config.jdb || {
+      root: "./data",
+      inMemory: false,
+    };
+    this.engine = new JDBEngine(jdbConfig);
+  }
+  async connect() {
+    await this.engine.connect();
+  }
+  async disconnect() {
+    await this.engine.disconnect();
+  }
+  async query(q) {
+    if (typeof q === "string") {
+      throw new Error(
+        "Raw string queries not supported in JDB directly. Use object syntax.",
+      );
+    }
+    if ("sql" in q) {
+      throw new Error("SQL queries not supported in JDB driver.");
+    }
+    const query = q;
+    const coll = this.engine.collection(query.find);
+    return await coll.find(query.where || {}, query.options);
+  }
+  async create(collection, data) {
+    return await this.engine.collection(collection).insert(data);
+  }
+  async update(collection, filter, update) {
+    return await this.engine
+      .collection(collection)
+      .update(filter, update, true);
+  }
+  async delete(collection, filter) {
+    return await this.engine.collection(collection).delete(filter, true);
+  }
+  async count(collection, filter) {
+    return await this.engine.collection(collection).count(filter);
+  }
 }