@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/server/src/services/MockDataService.ts

@@ -0,0 +1,347 @@
+/**
+ * MockDataService - In-memory data store with faker-based mock generation
+ *
+ * Provides a stateful mock data layer that supports all CRUD operations.
+ * Uses @faker-js/faker for realistic data generation based on field types.
+ *
+ * @packageDocumentation
+ */
+
+import { faker } from '@faker-js/faker';
+import { env } from '@/lib/env';
+import { logger } from '@/lib/logger';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface FieldSchema {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'relation' | 'array';
+  required?: boolean;
+  enumValues?: string[];
+  min?: number;
+  max?: number;
+  fakerMethod?: string;
+  relatedEntity?: string;
+}
+
+export interface EntitySchema {
+  fields: FieldSchema[];
+  seedCount?: number;
+}
+
+interface BaseEntity {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// ============================================================================
+// MockDataService
+// ============================================================================
+
+/**
+ * In-memory mock data store with CRUD operations and faker-based seeding.
+ */
+export class MockDataService {
+  private stores: Map<string, Map<string, unknown>> = new Map();
+  private schemas: Map<string, EntitySchema> = new Map();
+  private idCounters: Map<string, number> = new Map();
+
+  constructor() {
+    // Set seed for deterministic generation if provided
+    if (env.MOCK_SEED !== undefined) {
+      faker.seed(env.MOCK_SEED);
+      logger.info(`[Mock] Using seed: ${env.MOCK_SEED}`);
+    }
+  }
+
+  // ============================================================================
+  // Store Management
+  // ============================================================================
+
+  /**
+   * Initialize store for an entity.
+   */
+  private getStore(entityName: string): Map<string, unknown> {
+    const normalized = entityName.toLowerCase();
+    if (!this.stores.has(normalized)) {
+      this.stores.set(normalized, new Map());
+      this.idCounters.set(normalized, 0);
+    }
+    return this.stores.get(normalized)!;
+  }
+
+  /**
+   * Generate next ID for an entity.
+   */
+  private nextId(entityName: string): string {
+    const normalized = entityName.toLowerCase();
+    const counter = (this.idCounters.get(normalized) ?? 0) + 1;
+    this.idCounters.set(normalized, counter);
+    return `mock-${normalized}-${counter}`;
+  }
+
+  // ============================================================================
+  // Schema & Seeding
+  // ============================================================================
+
+  /**
+   * Register an entity schema.
+   */
+  registerSchema(entityName: string, schema: EntitySchema): void {
+    this.schemas.set(entityName.toLowerCase(), schema);
+  }
+
+  /**
+   * Seed an entity with mock data.
+   */
+  seed(entityName: string, fields: FieldSchema[], count: number = 10): void {
+    const store = this.getStore(entityName);
+    const normalized = entityName.toLowerCase();
+
+    logger.info(`[Mock] Seeding ${count} ${entityName}...`);
+
+    for (let i = 0; i < count; i++) {
+      const item = this.generateMockItem(normalized, fields, i + 1);
+      store.set(item.id, item);
+    }
+  }
+
+  /**
+   * Generate a single mock item based on field schemas.
+   */
+  private generateMockItem(entityName: string, fields: FieldSchema[], index: number): BaseEntity & Record<string, unknown> {
+    const id = this.nextId(entityName);
+    const now = new Date();
+    const item: Record<string, unknown> = {
+      id,
+      createdAt: faker.date.past({ years: 1 }),
+      updatedAt: now,
+    };
+
+    for (const field of fields) {
+      if (field.name === 'id' || field.name === 'createdAt' || field.name === 'updatedAt') {
+        continue;
+      }
+      item[field.name] = this.generateFieldValue(entityName, field, index);
+    }
+
+    return item as BaseEntity & Record<string, unknown>;
+  }
+
+  /**
+   * Generate a mock value for a field based on its schema.
+   */
+  private generateFieldValue(entityName: string, field: FieldSchema, index: number): unknown {
+    // Handle optional fields - 80% chance of having a value
+    if (!field.required && Math.random() > 0.8) {
+      return undefined;
+    }
+
+    switch (field.type) {
+      case 'string':
+        return this.generateStringValue(entityName, field, index);
+
+      case 'number':
+        return faker.number.int({
+          min: field.min ?? 0,
+          max: field.max ?? 1000,
+        });
+
+      case 'boolean':
+        return faker.datatype.boolean();
+
+      case 'date':
+        return this.generateDateValue(field);
+
+      case 'enum':
+        if (field.enumValues && field.enumValues.length > 0) {
+          return faker.helpers.arrayElement(field.enumValues);
+        }
+        return null;
+
+      case 'relation':
+        // For relations, generate a placeholder ID or null
+        if (field.relatedEntity) {
+          const relatedStore = this.stores.get(field.relatedEntity.toLowerCase());
+          if (relatedStore && relatedStore.size > 0) {
+            const ids = Array.from(relatedStore.keys());
+            return faker.helpers.arrayElement(ids);
+          }
+        }
+        return null;
+
+      case 'array':
+        // Generate an empty array for now
+        return [];
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Generate a string value based on field name heuristics.
+   * Generic name/title fields use entity-aware format (e.g., "Project Name 1").
+   * Specific fields (email, phone, etc.) use faker.
+   */
+  private generateStringValue(entityName: string, field: FieldSchema, index: number): string {
+    const name = field.name.toLowerCase();
+
+    // If field has enumValues, use them (even if type is 'string')
+    if (field.enumValues && field.enumValues.length > 0) {
+      return faker.helpers.arrayElement(field.enumValues);
+    }
+
+    // Specific fields - use faker for realistic data
+    if (name.includes('email')) return faker.internet.email();
+    if (name.includes('phone')) return faker.phone.number();
+    if (name.includes('address')) return faker.location.streetAddress();
+    if (name.includes('city')) return faker.location.city();
+    if (name.includes('country')) return faker.location.country();
+    if (name.includes('url') || name.includes('website')) return faker.internet.url();
+    if (name.includes('avatar') || name.includes('image')) return faker.image.avatar();
+    if (name.includes('color')) return faker.color.human();
+    if (name.includes('uuid')) return faker.string.uuid();
+
+    // Generic name/title/text fields - use entity-aware readable format
+    // Capitalize entity name and field name: "Project Name 1", "Task Title 1"
+    const entityLabel = this.capitalizeFirst(entityName);
+    const fieldLabel = this.capitalizeFirst(field.name);
+    return `${entityLabel} ${fieldLabel} ${index}`;
+  }
+
+  /**
+   * Capitalize first letter of a string.
+   */
+  private capitalizeFirst(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+
+  /**
+   * Generate a date value based on field name heuristics.
+   */
+  private generateDateValue(field: FieldSchema): Date {
+    const name = field.name.toLowerCase();
+
+    if (name.includes('created') || name.includes('start') || name.includes('birth')) {
+      return faker.date.past({ years: 2 });
+    }
+    if (name.includes('updated') || name.includes('modified')) {
+      return faker.date.recent({ days: 30 });
+    }
+    if (name.includes('deadline') || name.includes('due') || name.includes('end') || name.includes('expires')) {
+      return faker.date.future({ years: 1 });
+    }
+
+    return faker.date.anytime();
+  }
+
+  // ============================================================================
+  // CRUD Operations
+  // ============================================================================
+
+  /**
+   * List all items of an entity.
+   */
+  list<T>(entityName: string): T[] {
+    const store = this.getStore(entityName);
+    return Array.from(store.values()) as T[];
+  }
+
+  /**
+   * Get a single item by ID.
+   */
+  getById<T>(entityName: string, id: string): T | null {
+    const store = this.getStore(entityName);
+    const item = store.get(id);
+    return (item as T) ?? null;
+  }
+
+  /**
+   * Create a new item.
+   */
+  create<T extends BaseEntity>(entityName: string, data: Partial<T>): T {
+    const store = this.getStore(entityName);
+    const id = this.nextId(entityName);
+    const now = new Date();
+
+    const item = {
+      ...data,
+      id,
+      createdAt: now,
+      updatedAt: now,
+    } as T;
+
+    store.set(id, item);
+    return item;
+  }
+
+  /**
+   * Update an existing item.
+   */
+  update<T extends BaseEntity>(entityName: string, id: string, data: Partial<T>): T | null {
+    const store = this.getStore(entityName);
+    const existing = store.get(id);
+
+    if (!existing) {
+      return null;
+    }
+
+    const updated = {
+      ...(existing as T),
+      ...data,
+      id, // Preserve original ID
+      updatedAt: new Date(),
+    } as T;
+
+    store.set(id, updated);
+    return updated;
+  }
+
+  /**
+   * Delete an item.
+   */
+  delete(entityName: string, id: string): boolean {
+    const store = this.getStore(entityName);
+    if (!store.has(id)) {
+      return false;
+    }
+    store.delete(id);
+    return true;
+  }
+
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+
+  /**
+   * Clear all data for an entity.
+   */
+  clear(entityName: string): void {
+    const normalized = entityName.toLowerCase();
+    this.stores.delete(normalized);
+    this.idCounters.delete(normalized);
+  }
+
+  /**
+   * Clear all data.
+   */
+  clearAll(): void {
+    this.stores.clear();
+    this.idCounters.clear();
+  }
+
+  /**
+   * Get count of items for an entity.
+   */
+  count(entityName: string): number {
+    const store = this.getStore(entityName);
+    return store.size;
+  }
+}
+
+// Singleton instance
+export const mockDataService = new MockDataService();

package/shells/typescript-shell/packages/server/src/services/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Services barrel export
+ *
+ * @packageDocumentation
+ */
+
+export { mockDataService, type FieldSchema, type EntitySchema } from './MockDataService.js';
+export { dataService, seedMockData, type DataService, type EntitySeedConfig } from './DataService.js';

package/shells/typescript-shell/packages/server/src/types/express.d.ts

@@ -0,0 +1,13 @@
+import type { DecodedIdToken } from 'firebase-admin/auth';
+
+declare global {
+  namespace Express {
+    interface Request {
+      firebaseUser?: DecodedIdToken;
+    }
+  }
+}
+
+export {};
+
+

package/shells/typescript-shell/packages/server/src/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Server Utilities
+ *
+ * Reusable utility functions for Express routes and handlers.
+ *
+ * @packageDocumentation
+ */
+
+export * from './queryFilters.js';

package/shells/typescript-shell/packages/server/src/utils/queryFilters.ts

@@ -0,0 +1,231 @@
+/**
+ * Query Filter Utilities
+ *
+ * Parses URL query parameters into Firestore-compatible filter objects.
+ * Supports operator encoding in parameter names: field__operator=value
+ *
+ * @example
+ * // URL: /api/tasks?status=active&date__gte=2025-01-01&tags__contains=urgent
+ * const filters = parseQueryFilters(req.query);
+ * // Returns:
+ * // [
+ * //   { field: 'status', operator: '==', value: 'active' },
+ * //   { field: 'date', operator: '>=', value: '2025-01-01' },
+ * //   { field: 'tags', operator: 'array-contains', value: 'urgent' }
+ * // ]
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parsed filter ready for Firestore query
+ */
+export interface ParsedFilter {
+  field: string;
+  operator: FirestoreWhereFilterOp;
+  value: unknown;
+}
+
+/**
+ * Firestore where filter operators
+ */
+export type FirestoreWhereFilterOp =
+  | '=='
+  | '!='
+  | '>'
+  | '>='
+  | '<'
+  | '<='
+  | 'array-contains'
+  | 'array-contains-any'
+  | 'in'
+  | 'not-in';
+
+/**
+ * Map of URL operator suffixes to Firestore operators
+ */
+const OPERATOR_MAP: Record<string, FirestoreWhereFilterOp> = {
+  'eq': '==',
+  'neq': '!=',
+  'gt': '>',
+  'gte': '>=',
+  'lt': '<',
+  'lte': '<=',
+  'contains': 'array-contains',
+  'contains_any': 'array-contains-any',
+  'in': 'in',
+  'not_in': 'not-in',
+  // Date operators map to same comparison operators
+  'date_eq': '==',
+  'date_gte': '>=',
+  'date_lte': '<=',
+};
+
+/**
+ * Reserved query parameters that should not be treated as filters
+ */
+const RESERVED_PARAMS = new Set([
+  'page',
+  'pageSize',
+  'limit',
+  'offset',
+  'search',
+  'q',
+  'sortBy',
+  'sortOrder',
+  'orderBy',
+  'orderDirection',
+]);
+
+/**
+ * Parse query parameters into Firestore-compatible filters.
+ *
+ * Supports operator encoding: field__operator=value
+ *
+ * @param query - Express req.query object
+ * @returns Array of parsed filters ready for Firestore .where() calls
+ *
+ * @example
+ * ```typescript
+ * // In Express route handler:
+ * const filters = parseQueryFilters(req.query);
+ *
+ * let query = db.collection('tasks');
+ * for (const filter of filters) {
+ *   query = query.where(filter.field, filter.operator, filter.value);
+ * }
+ * ```
+ */
+export function parseQueryFilters(
+  query: Record<string, unknown>
+): ParsedFilter[] {
+  const filters: ParsedFilter[] = [];
+
+  for (const [key, value] of Object.entries(query)) {
+    // Skip reserved pagination/sort params
+    if (RESERVED_PARAMS.has(key)) continue;
+
+    // Skip empty values
+    if (value === undefined || value === null || value === '') continue;
+
+    // Parse operator from key: field__operator → { field, operator }
+    const match = key.match(/^(.+)__(\w+)$/);
+
+    if (match) {
+      const [, field, op] = match;
+      const firestoreOp = OPERATOR_MAP[op];
+
+      if (firestoreOp) {
+        filters.push({
+          field,
+          operator: firestoreOp,
+          value: parseValue(value, op),
+        });
+      } else {
+        // Unknown operator - treat as field name with double underscore
+        filters.push({
+          field: key,
+          operator: '==',
+          value: parseValue(value, 'eq'),
+        });
+      }
+    } else {
+      // No operator suffix → equals
+      filters.push({
+        field: key,
+        operator: '==',
+        value: parseValue(value, 'eq'),
+      });
+    }
+  }
+
+  return filters;
+}
+
+/**
+ * Parse and coerce value based on operator type
+ */
+function parseValue(value: unknown, operator: string): unknown {
+  // Handle array values for 'in' operator
+  if (operator === 'in' || operator === 'not_in' || operator === 'contains_any') {
+    if (typeof value === 'string') {
+      // Parse comma-separated values: "a,b,c" → ['a', 'b', 'c']
+      return value.split(',').map(v => v.trim());
+    }
+    if (Array.isArray(value)) {
+      return value;
+    }
+    return [value];
+  }
+
+  // Handle numeric values
+  if (typeof value === 'string') {
+    // Try to parse as number if it looks like one
+    if (/^-?\d+(\.\d+)?$/.test(value)) {
+      const num = parseFloat(value);
+      if (!isNaN(num)) {
+        return num;
+      }
+    }
+
+    // Handle boolean strings
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+  }
+
+  return value;
+}
+
+/**
+ * Build a Firestore query with filters applied.
+ *
+ * @param collection - Base Firestore collection reference or query
+ * @param filters - Parsed filters from parseQueryFilters
+ * @returns Query with all filters applied
+ *
+ * @example
+ * ```typescript
+ * const filters = parseQueryFilters(req.query);
+ * const baseQuery = db.collection('tasks');
+ * const filteredQuery = applyFiltersToQuery(baseQuery, filters);
+ * const snapshot = await filteredQuery.get();
+ * ```
+ */
+export function applyFiltersToQuery<T>(
+  collection: FirebaseFirestore.Query<T>,
+  filters: ParsedFilter[]
+): FirebaseFirestore.Query<T> {
+  let query = collection;
+
+  for (const filter of filters) {
+    query = query.where(
+      filter.field,
+      filter.operator as FirebaseFirestore.WhereFilterOp,
+      filter.value
+    );
+  }
+
+  return query;
+}
+
+/**
+ * Extract pagination parameters from query
+ */
+export interface PaginationParams {
+  page: number;
+  pageSize: number;
+  sortBy?: string;
+  sortOrder: 'asc' | 'desc';
+}
+
+export function extractPaginationParams(
+  query: Record<string, unknown>,
+  defaults: Partial<PaginationParams> = {}
+): PaginationParams {
+  return {
+    page: parseInt(query.page as string, 10) || defaults.page || 1,
+    pageSize: parseInt(query.pageSize as string, 10) || parseInt(query.limit as string, 10) || defaults.pageSize || 20,
+    sortBy: (query.sortBy || query.orderBy) as string | undefined,
+    sortOrder: ((query.sortOrder || query.orderDirection) as 'asc' | 'desc') || defaults.sortOrder || 'asc',
+  };
+}

package/shells/typescript-shell/packages/server/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@/*": ["./src/*"],
+      "@features/*": ["./src/features/*"],
+      "@lib/*": ["./src/lib/*"],
+      "@middleware/*": ["./src/middleware/*"],
+      "@routes/*": ["./src/routes/*"],
+      "@services/*": ["./src/services/*"],
+      "@shared/*": ["../shared/src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/shells/typescript-shell/packages/shared/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@almadar/shared",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}