create-jen-app 1.2.3 → 1.2.4

package/templates/ssr-isr/lib/graphql/index.js

@@ -0,0 +1,52 @@
+/**
+ * GraphQL integration utilities for Jen.js applications.
+ *
+ * Jen.js does not include GraphQL as a built-in dependency. This module provides
+ * a placeholder for GraphQL query execution and can be extended with custom implementations
+ * that use your chosen GraphQL library.
+ *
+ * To integrate GraphQL:
+ * 1. Install: npm install graphql
+ * 2. Import the graphql library: import { graphql } from 'graphql';
+ * 3. Implement query execution using your schema
+ * 4. Use in API routes or loaders
+ *
+ * @example
+ * // In an API route:
+ * import { runQuery } from '@src/graphql';
+ *
+ * export default {
+ *   handler: async (ctx) => {
+ *     const result = await runQuery(ctx.body.query, ctx.body.variables);
+ *     ctx.response.json(result);
+ *   }
+ * };
+ */
+/**
+ * Execute a GraphQL query.
+ * This is a placeholder function that must be implemented with your GraphQL library.
+ *
+ * @param query The GraphQL query string.
+ * @param variables Optional variables object for parameterized queries.
+ * @returns The query result object with data and errors (if any).
+ * @throws Error indicating GraphQL library must be installed.
+ *
+ * @example
+ * // Once graphql is installed:
+ * import { graphql } from 'graphql';
+ * import { schema } from './schema';
+ *
+ * export async function runQuery(query: string, variables?: any) {
+ *   const result = await graphql({
+ *     schema,
+ *     source: query,
+ *     variableValues: variables
+ *   });
+ *   return result;
+ * }
+ */
+export async function runQuery(query, variables) {
+  throw new Error(
+    "GraphQL implementation requires external library. Install: npm install graphql",
+  );
+}

package/templates/ssr-isr/lib/graphql/resolvers.js

@@ -0,0 +1,25 @@
+/** In-memory user store for example resolvers. Replace with database queries. */
+const users = [];
+/**
+ * Example resolvers for user queries and mutations.
+ * These are simple demonstrations using an in-memory store.
+ * In a real application, resolvers should query your database (JDB, etc.).
+ */
+export const resolvers = {
+  /**
+   * Query all users.
+   * @returns Array of all users.
+   */
+  users: () => users,
+  /**
+   * Create a new user.
+   * @param name User's full name.
+   * @param email User's email address.
+   * @returns The created user object with an ID.
+   */
+  createUser: ({ name, email }) => {
+    const user = { id: (users.length + 1).toString(), name, email };
+    users.push(user);
+    return user;
+  },
+};

package/templates/ssr-isr/lib/graphql/schema.js

@@ -0,0 +1,35 @@
+/**
+ * GraphQL schema placeholder module.
+ *
+ * Jen.js does not include GraphQL as a built-in dependency to keep the framework lightweight.
+ * GraphQL support is opt-in: users can integrate GraphQL by installing the graphql package
+ * and defining their own schemas in this module or elsewhere in their application.
+ *
+ * To use GraphQL with Jen.js:
+ * 1. Install the graphql package: npm install graphql
+ * 2. Define your schema using the graphql library
+ * 3. Create API routes that execute queries against the schema
+ *
+ * @example
+ * // Install: npm install graphql
+ * // src/graphql/schema.ts
+ *
+ * import { GraphQLSchema, GraphQLObjectType, GraphQLString, GraphQLField } from 'graphql';
+ *
+ * export const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       hello: {
+ *         type: GraphQLString,
+ *         resolve: () => 'Hello, World!'
+ *       }
+ *     }
+ *   })
+ * });
+ */
+/**
+ * Placeholder export for the GraphQL schema.
+ * Replace with your actual schema once graphql is installed.
+ */
+export const schema = null;

package/templates/ssr-isr/lib/i18n/en.json

@@ -0,0 +1,4 @@
+{
+  "hello": "Hello",
+  "welcome": "Welcome"
+}

package/templates/ssr-isr/lib/i18n/es.json

@@ -0,0 +1,4 @@
+{
+  "hello": "Hola",
+  "welcome": "Bienvenido"
+}

package/templates/ssr-isr/lib/i18n/index.js

@@ -0,0 +1,15 @@
+import en from "./en.json";
+import es from "./es.json";
+const translations = { en, es };
+export class I18n {
+  locale;
+  constructor(defaultLocale = "en") {
+    this.locale = defaultLocale;
+  }
+  setLocale(locale) {
+    this.locale = locale;
+  }
+  t(key) {
+    return translations[this.locale][key] || key;
+  }
+}

package/templates/ssr-isr/lib/import/jen-import.js

@@ -0,0 +1,161 @@
+import { buildSync } from "esbuild";
+import { pathToFileURL } from "node:url";
+import { join, resolve, extname } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { log } from "../shared/log.js";
+import {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+} from "../compilers/esbuild-plugins.js";
+/** In-memory cache mapping file paths to imported modules. Enables fast repeated imports. */
+const importCache = new Map();
+/**
+ * Resolve the cache directory path for a compiled module.
+ * Uses a flattened naming scheme to work reliably on Windows and other systems.
+ * Compiled modules are cached in node_modules/.jen/import-cache and are typically .gitignored.
+ *
+ * @param filePath The absolute path to the original source file.
+ * @returns The absolute path to the cached compiled .mjs file.
+ */
+function getCachePath(filePath) {
+  const cacheDir = join(process.cwd(), "node_modules", ".jen", "import-cache");
+  if (!existsSync(cacheDir)) {
+    mkdirSync(cacheDir, { recursive: true });
+  }
+  const flatName = filePath.replace(/[\\/:]/g, "_").replace(/^_+/, "");
+  return join(cacheDir, flatName + ".mjs");
+}
+/**
+ * Generate an ETag hash for a file to detect changes.
+ * Uses SHA1 for speed and sufficient collision resistance for this use case.
+ *
+ * @param content The file content to hash.
+ * @returns A 40-character hex string representing the hash.
+ */
+function generateEtag(content) {
+  return createHash("sha1").update(content).digest("hex");
+}
+/**
+ * Universal module importer for Vue, Svelte, and regular JS/TS files.
+ * Handles transpilation and caching to enable dynamic imports of framework components
+ * and utility modules with automatic compilation.
+ *
+ * Supported file types: .vue, .svelte, .ts, .tsx, .js, .jsx.
+ * Transpilation is performed using esbuild with Vue and Svelte plugins.
+ * Compiled modules are cached in node_modules/.jen/import-cache for fast subsequent loads.
+ *
+ * @param specifier File path relative to baseDir (typically process.cwd() or a component directory).
+ * @param opts Import options.
+ * @param opts.baseDir Base directory for relative path resolution. Defaults to process.cwd().
+ * @param opts.cache Whether to use in-memory cache. Defaults to true.
+ * @param opts.forceRecompile If true, bypass cache and recompile the module.
+ * @returns The imported module object (exports).
+ * @throws Error if the file type is unsupported, the file cannot be read, or transpilation fails.
+ *
+ * @example
+ * const Button = await jenImport("./components/Button.vue");
+ * const Card = await jenImport("./ui/Card.svelte");
+ * const Utils = await jenImport("./utils.ts", { cache: true });
+ * const Fresh = await jenImport("./component.tsx", { forceRecompile: true });
+ */
+export async function jenImport(specifier, opts) {
+  const baseDir = opts?.baseDir ?? process.cwd();
+  const useCache = opts?.cache !== false;
+  const forceRecompile = opts?.forceRecompile ?? false;
+  try {
+    // Resolve the file path relative to baseDir
+    const filePath = resolve(baseDir, specifier);
+    const ext = extname(filePath);
+    // Check cache first if enabled and not forcing recompile
+    if (useCache && !forceRecompile && importCache.has(filePath)) {
+      log.info(`[jen.import] Cache hit: ${specifier}`);
+      return importCache.get(filePath).module;
+    }
+    const isVue = ext === ".vue";
+    const isSvelte = ext === ".svelte";
+    const isTs = ext === ".ts" || ext === ".tsx";
+    // Validate file type
+    if (!isVue && !isSvelte && !isTs && ext !== ".js" && ext !== ".jsx") {
+      throw new Error(
+        `Unsupported file type: ${ext}. Supported: .vue, .svelte, .ts, .tsx, .js, .jsx`,
+      );
+    }
+    log.info(`[jen.import] Loading: ${specifier} (${ext})`);
+    const outfile = getCachePath(filePath);
+    // Transpile the module using esbuild with appropriate plugins
+    // Platform is set to "browser" for client-side components
+    // Bundle is false to preserve imports and enable tree-shaking
+    const result = buildSync({
+      entryPoints: [filePath],
+      outfile,
+      format: "esm",
+      platform: "browser",
+      target: "es2022",
+      bundle: false, // Don't bundle to preserve imports
+      write: true,
+      plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
+      external: [
+        "preact",
+        "preact/hooks",
+        "preact/jsx-runtime",
+        "preact-render-to-string",
+        "vue",
+        "svelte",
+      ],
+      logLevel: "error",
+      define: {
+        "process.env.NODE_ENV": JSON.stringify("development"),
+      },
+    });
+    // Dynamic import with cache-busting query parameter
+    // Prevents Node.js from caching the old module on repeated imports
+    const moduleUrl = pathToFileURL(outfile).href + "?t=" + Date.now();
+    const mod = await import(moduleUrl);
+    // Cache the imported module if caching is enabled
+    if (useCache) {
+      importCache.set(filePath, {
+        module: mod,
+        etag: generateEtag(outfile),
+      });
+    }
+    log.info(`[jen.import] Successfully loaded: ${specifier}`);
+    return mod;
+  } catch (err) {
+    const message = err.message || String(err);
+    log.error(`[jen.import] Failed to import "${specifier}": ${message}`);
+    throw new Error(`jen.import() failed for "${specifier}": ${message}`);
+  }
+}
+/**
+ * Invalidate the import cache for a specific file.
+ * Forces the next import to recompile the module from source.
+ * Useful during development when code changes frequently and cache may be stale.
+ *
+ * @param specifier File path (relative to process.cwd()) to invalidate.
+ */
+export function invalidateImportCache(specifier) {
+  const filePath = resolve(process.cwd(), specifier);
+  importCache.delete(filePath);
+  log.info(`[jen.import] Cache invalidated: ${specifier}`);
+}
+/**
+ * Clear all import caches completely.
+ * Forces all subsequent imports to recompile from source.
+ * Should be called sparingly; typically used when restarting the development server.
+ */
+export function clearImportCache() {
+  importCache.clear();
+  log.info(`[jen.import] All caches cleared`);
+}
+/**
+ * Global jen namespace providing access to jen.import() for dynamic module loading.
+ * Can be used as an alternative to calling jenImport() directly.
+ *
+ * @example
+ * import { jen } from '@src/import/jen-import';
+ * const Component = await jen.import('./Component.vue');
+ */
+export const jen = {
+  import: jenImport,
+};

package/templates/ssr-isr/lib/index.js

@@ -0,0 +1,116 @@
+// ============================================================================
+// Barrel Export: Automatically exports everything from all nested modules
+// ============================================================================
+// API
+export * from "./api/(hello).js";
+// Auth
+export * from "./auth/index.js";
+// Build
+export { buildSite as legacyBuildSite } from "./build-tools/build-site.js";
+export * from "./build/build.js";
+export { ProductionBuilder } from "./build/production-build.js";
+export { SSGPipeline } from "./build/ssg-pipeline.js";
+export * from "./build/island-hydration.js";
+export { AssetManifest } from "./build/asset-manifest.js";
+export { AssetHasher } from "./build/asset-hashing.js";
+export { PageRenderer } from "./build/page-renderer.js";
+export { Minifier } from "./build/minifier.js";
+export {
+  createIslandRegistry,
+  markIsland,
+  extractIslandsFromHtml,
+  injectIslandScript,
+} from "./build/island-hydration.js";
+// Cache
+export * from "./cache/index.js";
+export * from "./cache/memory.js";
+export * from "./cache/redis.js";
+// CLI
+export * from "./cli/templates/ssg/jen.config.js";
+export * from "./cli/templates/ssr/jen.config.js";
+export * from "./cli/banner.js";
+// Compilers
+export { createVueCompiler } from "./compilers/vue.js";
+export { createSvelteCompiler } from "./compilers/svelte.js";
+export {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+  invalidateVueCache,
+  invalidateSvelteCache,
+  clearAllCompilerCaches,
+} from "./compilers/esbuild-plugins.js";
+// Core
+export * from "./core/config.js";
+export * from "./core/http.js";
+export * from "./core/paths.js";
+export * from "./core/types.js";
+export * from "./core/routes/match.js";
+export * from "./core/routes/scan.js";
+export * from "./core/middleware-hooks.js";
+// CSS
+export * from "./css/compiler.js";
+// Database
+export * from "./db/index.js";
+export * from "./db/types.js";
+export * from "./db/connector.js";
+export * from "./db/drivers/sql.js";
+export * from "./db/drivers/jdb.js";
+// GraphQL
+export * from "./graphql/index.js";
+export * from "./graphql/schema.js";
+export * from "./graphql/resolvers.js";
+// i18n
+export * from "./i18n/index.js";
+// Import utilities
+export {
+  jenImport,
+  clearImportCache,
+  invalidateImportCache,
+  jen,
+} from "./import/jen-import.js";
+// JDB
+export * from "./jdb/index.js";
+export * from "./jdb/engine.js";
+export * from "./jdb/types.js";
+export * from "./jdb/utils.js";
+// Middleware
+export * from "./middleware/types.js";
+export * from "./middleware/context.js";
+export * from "./middleware/response.js";
+export * from "./middleware/pipeline.js";
+export * from "./middleware/kernel.js";
+export * from "./middleware/registry.js";
+export * from "./middleware/decorators.js";
+export * from "./middleware/builtins/logger.js";
+export * from "./middleware/builtins/request-id.js";
+export * from "./middleware/builtins/security-headers.js";
+export * from "./middleware/builtins/cors.js";
+export * from "./middleware/builtins/body-parser.js";
+export * from "./middleware/builtins/rate-limit.js";
+export * from "./middleware/errors/http-error.js";
+export * from "./middleware/errors/handler.js";
+export * from "./middleware/utils/matcher.js";
+// Native
+export * from "./native/index.js";
+export * from "./native/bundle.js";
+export * from "./native/dev-server.js";
+export * from "./native/optimizer.js";
+export * from "./native/style-compiler.js";
+// Plugin
+export * from "./plugin/loader.js";
+// Runtime
+export * from "./runtime/render.js";
+export * from "./runtime/client-runtime.js";
+export * from "./runtime/hydrate.js";
+export * from "./runtime/hmr.js";
+export * from "./runtime/islands.js";
+export * from "./runtime/island-hydration-client.js";
+// Server
+export * from "./server/app.js";
+// Use new api-routes.ts for HTTP method handlers (replaces old api.js behavior)
+export { tryHandleApiRoute as tryHandleApiRoute_v2 } from "./server/api-routes.js";
+// Keep old api.js exports for backward compatibility
+export { tryHandleApiRoute } from "./server/api.js";
+export * from "./server/runtimeServe.js";
+// Shared utilities
+export * from "./shared/log.js";

package/templates/ssr-isr/lib/jdb/engine.js

@@ -0,0 +1,275 @@
+import path from "path";
+import {
+  ensureDir,
+  readJSON,
+  writeJSON,
+  generateId,
+  matchFilter,
+  applyUpdate,
+} from "./utils";
+/**
+ * In-memory representation of a single collection.
+ * Manages document storage, serialization, and basic file I/O.
+ * Supports lazy loading of data from disk and deferred save operations to batch writes.
+ *
+ * @template T Document type, must extend the Document base type.
+ */
+class JDBCollection {
+  name;
+  dir;
+  inMemory;
+  /** Absolute path to the .jdb file for this collection. */
+  file;
+  /** In-memory array of documents. */
+  data = [];
+  /** Flag indicating whether the data has been loaded from disk. */
+  loaded = false;
+  /** Flag indicating a save operation is currently in progress. */
+  saving = false;
+  /** Flag indicating a save was requested while another save was in progress. Triggers another save after current one completes. */
+  queueSave = false;
+  /**
+   * Create a new collection instance.
+   * Does not load data until an operation requires it (lazy loading).
+   *
+   * @param name Name of the collection.
+   * @param dir Directory where collection files are stored.
+   * @param inMemory If true, data is never persisted to disk.
+   */
+  constructor(name, dir, inMemory) {
+    this.name = name;
+    this.dir = dir;
+    this.inMemory = inMemory;
+    this.file = path.join(dir, `${name}.jdb`);
+  }
+  /**
+   * Load collection data from disk on first access.
+   * Uses lazy loading to defer file I/O until actually needed.
+   * In-memory collections skip disk reads entirely.
+   * Idempotent: subsequent calls return immediately if already loaded.
+   */
+  async load() {
+    if (this.loaded) return;
+    if (!this.inMemory) {
+      await ensureDir(this.dir);
+      const content = await readJSON(this.file);
+      this.data = content || [];
+    }
+    this.loaded = true;
+  }
+  /**
+   * Persist collection data to disk.
+   * Uses a queue mechanism to batch multiple rapid modifications into a single write.
+   * If a save is already in progress, queues the next save to run after current one completes.
+   * In-memory collections skip disk writes entirely.
+   */
+  async save() {
+    if (this.inMemory) return;
+    if (this.saving) {
+      this.queueSave = true;
+      return;
+    }
+    this.saving = true;
+    try {
+      await writeJSON(this.file, this.data);
+    } finally {
+      this.saving = false;
+      if (this.queueSave) {
+        this.queueSave = false;
+        this.save();
+      }
+    }
+  }
+  /**
+   * Insert a single document into the collection.
+   * Automatically assigns a UUID for _id (if not provided) and timestamps for _created and _updated.
+   * Queues a save operation to persist the document.
+   *
+   * @param doc The document to insert, without system fields.
+   * @returns The inserted document with _id, _created, and _updated populated.
+   */
+  async insert(doc) {
+    await this.load();
+    const now = Date.now();
+    const newDoc = {
+      _id: doc._id || generateId(),
+      _created: now,
+      _updated: now,
+      ...doc,
+    };
+    this.data.push(newDoc);
+    this.save();
+    return newDoc;
+  }
+  /**
+   * Insert multiple documents into the collection atomically.
+   * All documents are assigned the same _created timestamp.
+   * Queues a single save operation to persist all documents.
+   *
+   * @param docs Array of documents to insert.
+   * @returns Array of inserted documents with all system fields populated.
+   */
+  async insertMany(docs) {
+    await this.load();
+    const now = Date.now();
+    const newDocs = docs.map((doc) => ({
+      _id: doc._id || generateId(),
+      _created: now,
+      _updated: now,
+      ...doc,
+    }));
+    this.data.push(...newDocs);
+    this.save();
+    return newDocs;
+  }
+  /**
+   * Find the first document matching the filter.
+   *
+   * @param filter Query filter to apply.
+   * @returns The first matching document, or null if no match found.
+   */
+  async findOne(filter) {
+    await this.load();
+    return this.data.find((doc) => matchFilter(doc, filter)) || null;
+  }
+  /**
+   * Find all documents matching the filter with optional sorting and pagination.
+   * Applies sort, skip, and limit in that order for correct pagination behavior.
+   *
+   * @param filter Query filter to apply.
+   * @param options Optional QueryOptions for sorting, skipping, and limiting results.
+   * @returns Array of matching documents (empty array if no matches).
+   */
+  async find(filter, options) {
+    await this.load();
+    let result = this.data.filter((doc) => matchFilter(doc, filter));
+    if (options?.sort) {
+      const sortKeys = Object.keys(options.sort);
+      result.sort((a, b) => {
+        for (const key of sortKeys) {
+          const dir = options.sort[key];
+          if (a[key] < b[key]) return -1 * dir;
+          if (a[key] > b[key]) return 1 * dir;
+        }
+        return 0;
+      });
+    }
+    if (options?.skip) {
+      result = result.slice(options.skip);
+    }
+    if (options?.limit) {
+      result = result.slice(0, options.limit);
+    }
+    return result;
+  }
+  /**
+   * Update document(s) matching the filter.
+   * Applies update operators atomically and updates the _updated timestamp.
+   * By default, updates only the first matching document. Set multi=true to update all.
+   *
+   * @param filter Query filter to select documents to update.
+   * @param update Update operators and values to apply.
+   * @param multi If false (default), updates only first match. If true, updates all matches.
+   * @returns Count of documents updated.
+   */
+  async update(filter, update, multi = false) {
+    await this.load();
+    let count = 0;
+    for (const doc of this.data) {
+      if (matchFilter(doc, filter)) {
+        applyUpdate(doc, update);
+        count++;
+        if (!multi) break;
+      }
+    }
+    if (count > 0) this.save();
+    return count;
+  }
+  /**
+   * Delete document(s) matching the filter.
+   * By default, deletes only the first matching document. Set multi=true to delete all.
+   *
+   * @param filter Query filter to select documents to delete.
+   * @param multi If false (default), deletes only first match. If true, deletes all matches.
+   * @returns Count of documents deleted.
+   */
+  async delete(filter, multi = false) {
+    await this.load();
+    const originalLen = this.data.length;
+    if (!multi) {
+      const index = this.data.findIndex((doc) => matchFilter(doc, filter));
+      if (index !== -1) {
+        this.data.splice(index, 1);
+        this.save();
+        return 1;
+      }
+      return 0;
+    } else {
+      this.data = this.data.filter((doc) => !matchFilter(doc, filter));
+      const deleted = originalLen - this.data.length;
+      if (deleted > 0) this.save();
+      return deleted;
+    }
+  }
+  /**
+   * Count documents matching the filter.
+   *
+   * @param filter Query filter to apply.
+   * @returns Number of documents matching the filter.
+   */
+  async count(filter) {
+    await this.load();
+    return this.data.filter((doc) => matchFilter(doc, filter)).length;
+  }
+}
+/**
+ * File-based database engine implementation.
+ * Stores collections as JSON files in the configured directory.
+ * Provides lazy collection initialization and in-memory option for testing.
+ */
+export class JDBEngine {
+  config;
+  /** Cached collection instances. Created on demand and reused for subsequent accesses. */
+  collections = new Map();
+  /**
+   * Create a new database engine instance.
+   *
+   * @param config Configuration specifying storage root directory and memory mode.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Establish database connection by ensuring the storage root directory exists.
+   * Creates the directory recursively if it doesn't exist.
+   */
+  async connect() {
+    await ensureDir(this.config.root);
+  }
+  /**
+   * Close database connection and clean up resources.
+   * Currently a no-op for file-based storage, but provided for compatibility with IDatabaseEngine interface.
+   * Future versions may flush pending writes or close file handles here.
+   */
+  async disconnect() {
+    // No-op for file based, maybe ensure all saves are flushed
+  }
+  /**
+   * Get or create a collection by name.
+   * Collections are cached after first access, so subsequent calls return the same instance.
+   * Uses lazy initialization: data is not loaded from disk until the collection is accessed.
+   *
+   * @template T Document type for the collection.
+   * @param name Unique name for the collection. Used to generate the .jdb filename.
+   * @returns Collection instance for CRUD operations.
+   */
+  collection(name) {
+    if (!this.collections.has(name)) {
+      this.collections.set(
+        name,
+        new JDBCollection(name, this.config.root, !!this.config.inMemory),
+      );
+    }
+    return this.collections.get(name);
+  }
+}