create-jen-app 1.2.1 → 1.2.3

package/templates/static/lib/import/jen-import.js

@@ -21,108 +21,158 @@ 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";
+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");
+  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");
+  return createHash("sha1").update(content).digest("hex");
 }
 /**
- * Universal module importer for Vue, Svelte, and regular JS/TS
+ * 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 jen.import("./components/Button.vue");
- * const Card = await jen.import("./ui/Card.svelte");
- * const Utils = await jen.import("./utils.ts");
+ * 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
-        const filePath = resolve(baseDir, specifier);
-        const ext = extname(filePath);
-        // Check cache first
-        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";
-        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);
-        // Build with appropriate plugins
-        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
-        const moduleUrl = pathToFileURL(outfile).href + "?t=" + Date.now();
-        const mod = await import(moduleUrl);
-        // Cache the imported module
-        if (useCache) {
-            importCache.set(filePath, {
-                module: mod,
-                etag: generateEtag(outfile),
-            });
-        }
-        log.info(`[jen.import] Successfully loaded: ${specifier}`);
-        return mod;
+  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`,
+      );
     }
-    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}`);
+    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}`);
+  }
 }
 /**
- * Clear import cache for a specific file
+ * 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}`);
+  const filePath = resolve(process.cwd(), specifier);
+  importCache.delete(filePath);
+  log.info(`[jen.import] Cache invalidated: ${specifier}`);
 }
 /**
- * Clear all import caches
+ * 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`);
+  importCache.clear();
+  log.info(`[jen.import] All caches cleared`);
 }
 /**
- * Export as global jen.import if needed
+ * 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,
+  import: jenImport,
 };

package/templates/static/lib/index.d.ts

@@ -1,11 +1,14 @@
 export * from "./api/(hello).js";
 export * from "./auth/index.js";
-export * from "./auth/jwt.js";
-export * from "./auth/session.js";
-export * from "./auth/cookie-utils.js";
-export { buildSite as legacyBuildSite, type BuildOptions, } from "./build-tools/build-site.js";
+export {
+  buildSite as legacyBuildSite,
+  type BuildOptions,
+} from "./build-tools/build-site.js";
 export * from "./build/build.js";
-export { ProductionBuilder, type ProductionBuildConfig, } from "./build/production-build.js";
+export {
+  ProductionBuilder,
+  type ProductionBuildConfig,
+} 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";
@@ -13,16 +16,35 @@ export { AssetHasher } from "./build/asset-hashing.js";
 export { PageRenderer, type PageRenderContext } from "./build/page-renderer.js";
 export { Minifier, type MinifyOptions } from "./build/minifier.js";
 export type { Island, IslandRegistry } from "./build/island-hydration.js";
-export { createIslandRegistry, markIsland, extractIslandsFromHtml, injectIslandScript, } from "./build/island-hydration.js";
+export {
+  createIslandRegistry,
+  markIsland,
+  extractIslandsFromHtml,
+  injectIslandScript,
+} from "./build/island-hydration.js";
 export * from "./cache/index.js";
 export * from "./cache/memory.js";
 export * from "./cache/redis.js";
 export * from "./cli/templates/ssg/jen.config.js";
 export * from "./cli/templates/ssr/jen.config.js";
 export * from "./cli/banner.js";
-export { createVueCompiler, type VueCompileOptions, type VueCompileResult } from "./compilers/vue.js";
-export { createSvelteCompiler, type SvelteCompileOptions, type SvelteCompileResult } from "./compilers/svelte.js";
-export { vueEsbuildPlugin, svelteEsbuildPlugin, invalidateVueCache, invalidateSvelteCache, clearAllCompilerCaches, } from "./compilers/esbuild-plugins.js";
+export {
+  createVueCompiler,
+  type VueCompileOptions,
+  type VueCompileResult,
+} from "./compilers/vue.js";
+export {
+  createSvelteCompiler,
+  type SvelteCompileOptions,
+  type SvelteCompileResult,
+} from "./compilers/svelte.js";
+export {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+  invalidateVueCache,
+  invalidateSvelteCache,
+  clearAllCompilerCaches,
+} from "./compilers/esbuild-plugins.js";
 export * from "./core/config.js";
 export * from "./core/http.js";
 export * from "./core/paths.js";
@@ -40,7 +62,12 @@ export * from "./graphql/index.js";
 export * from "./graphql/schema.js";
 export * from "./graphql/resolvers.js";
 export * from "./i18n/index.js";
-export { jenImport, clearImportCache, invalidateImportCache, jen } from "./import/jen-import.js";
+export {
+  jenImport,
+  clearImportCache,
+  invalidateImportCache,
+  jen,
+} from "./import/jen-import.js";
 export * from "./jdb/index.js";
 export * from "./jdb/engine.js";
 export * from "./jdb/types.js";
@@ -75,7 +102,11 @@ export * from "./runtime/islands.js";
 export * from "./runtime/island-hydration-client.js";
 export * from "./server/app.js";
 export { tryHandleApiRoute as tryHandleApiRoute_v2 } from "./server/api-routes.js";
-export type { ApiHandler, ApiRouteContext, ApiRouteModule, } from "./server/api-routes.js";
+export type {
+  ApiHandler,
+  ApiRouteContext,
+  ApiRouteModule,
+} from "./server/api-routes.js";
 export { tryHandleApiRoute } from "./server/api.js";
 export * from "./server/runtimeServe.js";
 export * from "./shared/log.js";

package/templates/static/lib/index.js

@@ -22,20 +22,22 @@
 export * from "./api/(hello).js";
 // Auth
 export * from "./auth/index.js";
-export * from "./auth/jwt.js";
-export * from "./auth/session.js";
-export * from "./auth/cookie-utils.js";
 // Build
-export { buildSite as legacyBuildSite, } from "./build-tools/build-site.js";
+export { buildSite as legacyBuildSite } from "./build-tools/build-site.js";
 export * from "./build/build.js";
-export { ProductionBuilder, } from "./build/production-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";
+export {
+  createIslandRegistry,
+  markIsland,
+  extractIslandsFromHtml,
+  injectIslandScript,
+} from "./build/island-hydration.js";
 // Cache
 export * from "./cache/index.js";
 export * from "./cache/memory.js";
@@ -47,7 +49,13 @@ 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";
+export {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+  invalidateVueCache,
+  invalidateSvelteCache,
+  clearAllCompilerCaches,
+} from "./compilers/esbuild-plugins.js";
 // Core
 export * from "./core/config.js";
 export * from "./core/http.js";
@@ -71,7 +79,12 @@ export * from "./graphql/resolvers.js";
 // i18n
 export * from "./i18n/index.js";
 // Import utilities
-export { jenImport, clearImportCache, invalidateImportCache, jen } from "./import/jen-import.js";
+export {
+  jenImport,
+  clearImportCache,
+  invalidateImportCache,
+  jen,
+} from "./import/jen-import.js";
 // JDB
 export * from "./jdb/index.js";
 export * from "./jdb/engine.js";

package/templates/static/lib/jdb/engine.d.ts

@@ -1,9 +1,38 @@
 import { JDBConfig, IDatabaseEngine, ICollection, Document } from "./types";
+/**
+ * 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 declare class JDBEngine implements IDatabaseEngine {
-    private config;
-    private collections;
-    constructor(config: JDBConfig);
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    collection<T extends Document>(name: string): ICollection<T>;
+  private config;
+  /** Cached collection instances. Created on demand and reused for subsequent accesses. */
+  private collections;
+  /**
+   * Create a new database engine instance.
+   *
+   * @param config Configuration specifying storage root directory and memory mode.
+   */
+  constructor(config: JDBConfig);
+  /**
+   * Establish database connection by ensuring the storage root directory exists.
+   * Creates the directory recursively if it doesn't exist.
+   */
+  connect(): Promise<void>;
+  /**
+   * 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.
+   */
+  disconnect(): Promise<void>;
+  /**
+   * 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<T extends Document>(name: string): ICollection<T>;
 }