create-jen-app 1.2.1 → 1.2.3

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

@@ -20,46 +20,46 @@ export * from "./types";
 export * from "./drivers/jdb";
 export * from "./drivers/sql";
 export class DB {
-    driver;
-    config;
-    constructor(config) {
-        this.config = config;
-        this.driver = DBConnector.create(config);
-    }
-    async connect() {
-        await this.driver.connect();
-    }
-    async disconnect() {
-        await this.driver.disconnect();
-    }
-    async query(q, params) {
-        if (typeof q === "string") {
-            return this.driver.query({ sql: q, params });
-        }
-        return this.driver.query(q);
-    }
-    // Fluent API Shortcuts
-    find(collection, filter, options) {
-        return this.driver.query({ find: collection, where: filter, options });
-    }
-    async findOne(collection, filter) {
-        const res = await this.driver.query({
-            find: collection,
-            where: filter,
-            options: { limit: 1 },
-        });
-        return res[0] || null;
-    }
-    create(collection, data) {
-        return this.driver.create(collection, data);
-    }
-    update(collection, filter, update) {
-        return this.driver.update(collection, filter, update);
-    }
-    delete(collection, filter) {
-        return this.driver.delete(collection, filter);
-    }
-    count(collection, filter) {
-        return this.driver.count(collection, filter);
+  driver;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.driver = DBConnector.create(config);
+  }
+  async connect() {
+    await this.driver.connect();
+  }
+  async disconnect() {
+    await this.driver.disconnect();
+  }
+  async query(q, params) {
+    if (typeof q === "string") {
+      return this.driver.query({ sql: q, params });
     }
+    return this.driver.query(q);
+  }
+  // Fluent API Shortcuts
+  find(collection, filter, options) {
+    return this.driver.query({ find: collection, where: filter, options });
+  }
+  async findOne(collection, filter) {
+    const res = await this.driver.query({
+      find: collection,
+      where: filter,
+      options: { limit: 1 },
+    });
+    return res[0] || null;
+  }
+  create(collection, data) {
+    return this.driver.create(collection, data);
+  }
+  update(collection, filter, update) {
+    return this.driver.update(collection, filter, update);
+  }
+  delete(collection, filter) {
+    return this.driver.delete(collection, filter);
+  }
+  count(collection, filter) {
+    return this.driver.count(collection, filter);
+  }
 }

package/templates/static/lib/db/types.d.ts

@@ -1,29 +1,33 @@
 import { Filter, Update, QueryOptions } from "../jdb/types";
 export type DBType = "jdb" | "sqlite" | "mysql" | "postgres";
 export interface DBConfig {
-    type: DBType;
-    connection?: any;
-    jdb?: {
-        root: string;
-        inMemory?: boolean;
-    };
+  type: DBType;
+  connection?: any;
+  jdb?: {
+    root: string;
+    inMemory?: boolean;
+  };
 }
 export type FindQuery<T = any> = {
-    find: string;
-    where?: Filter<T>;
-    options?: QueryOptions;
+  find: string;
+  where?: Filter<T>;
+  options?: QueryOptions;
 };
 export type SQLQuery = {
-    sql: string;
-    params?: any[];
+  sql: string;
+  params?: any[];
 };
 export type UnifiedQuery<T = any> = FindQuery<T> | SQLQuery | string;
 export interface IDBDriver {
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    query<T = any>(q: UnifiedQuery<T>): Promise<T[]>;
-    create<T = any>(collection: string, data: any): Promise<T>;
-    update<T = any>(collection: string, filter: Filter<T>, update: Update<T>): Promise<number>;
-    delete<T = any>(collection: string, filter: Filter<T>): Promise<number>;
-    count<T = any>(collection: string, filter: Filter<T>): Promise<number>;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  query<T = any>(q: UnifiedQuery<T>): Promise<T[]>;
+  create<T = any>(collection: string, data: any): Promise<T>;
+  update<T = any>(
+    collection: string,
+    filter: Filter<T>,
+    update: Update<T>,
+  ): Promise<number>;
+  delete<T = any>(collection: string, filter: Filter<T>): Promise<number>;
+  count<T = any>(collection: string, filter: Filter<T>): Promise<number>;
 }

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

@@ -1 +1,48 @@
+/**
+ * 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 declare function runQuery(query: string, variables?: any): Promise<void>;

package/templates/static/lib/graphql/index.js

@@ -15,8 +15,55 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
-// GraphQL utilities - external GraphQL library not included
-// Users should implement with their own graphql library (e.g., npm install graphql)
+/**
+ * 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");
+  throw new Error(
+    "GraphQL implementation requires external library. Install: npm install graphql",
+  );
 }

package/templates/static/lib/graphql/resolvers.d.ts

@@ -1,17 +1,57 @@
+/**
+ * GraphQL resolvers placeholder module.
+ *
+ * Jen.js provides basic example resolvers to demonstrate the pattern.
+ * Replace these with your actual resolvers that implement your application logic.
+ *
+ * Resolvers are functions that return the data for each field in your GraphQL schema.
+ * They have access to the parent value, arguments, context, and field info.
+ *
+ * @example
+ * // Custom resolver with database integration:
+ * import { db } from '@src/jdb';
+ *
+ * export const resolvers = {
+ *   users: async () => {
+ *     const users = db.collection('users');
+ *     return await users.find({});
+ *   },
+ *   createUser: async ({ name, email }: { name: string; email: string }) => {
+ *     const users = db.collection('users');
+ *     return await users.insert({ name, email });
+ *   }
+ * };
+ */
+/**
+ * Example user type for resolver demonstrations.
+ * Replace with your actual types defined in your schema.
+ */
 interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+/**
+ * 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 declare const resolvers: {
+  /**
+   * Query all users.
+   * @returns Array of all users.
+   */
+  users: () => User[];
+  /**
+   * 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 }: { name: string; email: string }) => {
     id: string;
     name: string;
     email: string;
-}
-export declare const resolvers: {
-    users: () => User[];
-    createUser: ({ name, email }: {
-        name: string;
-        email: string;
-    }) => {
-        id: string;
-        name: string;
-        email: string;
-    };
+  };
 };
 export {};

package/templates/static/lib/graphql/resolvers.js

@@ -15,12 +15,28 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
+/** 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 = {
-    users: () => users,
-    createUser: ({ name, email }) => {
-        const user = { id: (users.length + 1).toString(), name, email };
-        users.push(user);
-        return user;
-    },
+  /**
+   * 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/static/lib/graphql/schema.d.ts

@@ -1 +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 declare const schema: null;

package/templates/static/lib/graphql/schema.js

@@ -15,6 +15,38 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
-// GraphQL schema - external GraphQL library not included
-// Users should implement with their own graphql library (e.g., npm install graphql)
+/**
+ * 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/static/lib/i18n/en.json

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

package/templates/static/lib/i18n/es.json

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

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

@@ -1,8 +1,8 @@
 type Locale = "en" | "es";
 export declare class I18n {
-    private locale;
-    constructor(defaultLocale?: Locale);
-    setLocale(locale: Locale): void;
-    t(key: string): string;
+  private locale;
+  constructor(defaultLocale?: Locale);
+  setLocale(locale: Locale): void;
+  t(key: string): string;
 }
 export {};

package/templates/static/lib/i18n/index.js

@@ -19,14 +19,14 @@ 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;
-    }
+  locale;
+  constructor(defaultLocale = "en") {
+    this.locale = defaultLocale;
+  }
+  setLocale(locale) {
+    this.locale = locale;
+  }
+  t(key) {
+    return translations[this.locale][key] || key;
+  }
 }

package/templates/static/lib/import/jen-import.d.ts

@@ -1,27 +1,56 @@
 /**
- * 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 declare function jenImport(specifier: string, opts?: {
+export declare function jenImport(
+  specifier: string,
+  opts?: {
     baseDir?: string;
     cache?: boolean;
     forceRecompile?: boolean;
-}): Promise<any>;
+  },
+): Promise<any>;
 /**
- * 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 declare function invalidateImportCache(specifier: string): void;
 /**
- * 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 declare function clearImportCache(): void;
 /**
- * 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 declare const jen: {
-    import: typeof jenImport;
+  import: typeof jenImport;
 };