@htlkg/core 0.0.2 → 0.0.3

package/src/utils/index.ts

@@ -0,0 +1,112 @@
+/**
+ * @htlkg/core/utils
+ * Core utility functions for Hotelinking applications
+ */
+
+// Logger utility
+export { logger, createLogger } from './logger';
+
+/**
+ * Format a date to a localized string
+ * @param date - Date to format
+ * @param locale - Locale string (default: 'en-US')
+ * @param options - Intl.DateTimeFormatOptions
+ * @returns Formatted date string
+ */
+export function formatDate(
+	date: Date | string | number,
+	locale = "en-US",
+	options: Intl.DateTimeFormatOptions = {
+		year: "numeric",
+		month: "short",
+		day: "numeric",
+	},
+): string {
+	const dateObj = typeof date === "string" || typeof date === "number" ? new Date(date) : date;
+	return new Intl.DateTimeFormat(locale, options).format(dateObj);
+}
+
+/**
+ * Truncate text to a maximum length with ellipsis
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length before truncation
+ * @param suffix - Suffix to append (default: '...')
+ * @returns Truncated text
+ */
+export function truncateText(
+	text: string,
+	maxLength: number,
+	suffix = "...",
+): string {
+	if (text.length <= maxLength) return text;
+	return text.slice(0, maxLength - suffix.length) + suffix;
+}
+
+/**
+ * Group an array of items by a key
+ * @param items - Array of items to group
+ * @param keyFn - Function to extract the grouping key
+ * @returns Object with keys as group names and values as arrays of items
+ */
+export function groupBy<T>(
+	items: T[],
+	keyFn: (item: T) => string | number,
+): Record<string | number, T[]> {
+	return items.reduce(
+		(groups, item) => {
+			const key = keyFn(item);
+			if (!groups[key]) {
+				groups[key] = [];
+			}
+			groups[key].push(item);
+			return groups;
+		},
+		{} as Record<string | number, T[]>,
+	);
+}
+
+/**
+ * Debounce a function call
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export function debounce<T extends (...args: any[]) => any>(
+	fn: T,
+	delay: number,
+): (...args: Parameters<T>) => void {
+	let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+	return function debounced(...args: Parameters<T>) {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+		}
+		timeoutId = setTimeout(() => {
+			fn(...args);
+			timeoutId = null;
+		}, delay);
+	};
+}
+
+/**
+ * Throttle a function call
+ * @param fn - Function to throttle
+ * @param limit - Minimum time between calls in milliseconds
+ * @returns Throttled function
+ */
+export function throttle<T extends (...args: any[]) => any>(
+	fn: T,
+	limit: number,
+): (...args: Parameters<T>) => void {
+	let inThrottle = false;
+
+	return function throttled(...args: Parameters<T>) {
+		if (!inThrottle) {
+			fn(...args);
+			inThrottle = true;
+			setTimeout(() => {
+				inThrottle = false;
+			}, limit);
+		}
+	};
+}

package/src/utils/logger.ts

@@ -0,0 +1,88 @@
+/**
+ * Simple debug logger utility
+ * 
+ * Debug logs are only shown when DEBUG=true or HTLKG_DEBUG=true is set in environment.
+ * Info logs are always shown.
+ * 
+ * @example
+ * ```typescript
+ * import { logger } from '@htlkg/core/utils/logger';
+ * 
+ * logger.debug('server-client', 'Detailed debug info', { data });
+ * logger.info('server-client', 'Important info message');
+ * logger.warn('server-client', 'Warning message');
+ * logger.error('server-client', 'Error occurred', error);
+ * ```
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const isDebugEnabled = (): boolean => {
+  // Check Node.js environment variables
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.DEBUG === 'true' || 
+           process.env.HTLKG_DEBUG === 'true' ||
+           process.env.DEBUG === '*';
+  }
+  // Browser/Vite environment - check for DEV mode
+  try {
+    // @ts-ignore - import.meta.env is Vite-specific
+    if (typeof import.meta !== 'undefined' && import.meta.env) {
+      // @ts-ignore
+      return import.meta.env.DEBUG === 'true' || 
+             // @ts-ignore
+             import.meta.env.HTLKG_DEBUG === 'true' ||
+             // @ts-ignore
+             import.meta.env.DEV === true;
+    }
+  } catch {
+    // Ignore errors accessing import.meta
+  }
+  return false;
+};
+
+const formatMessage = (namespace: string, message: string): string => {
+  return `[${namespace}] ${message}`;
+};
+
+export const logger = {
+  /**
+   * Debug log - only shown when DEBUG=true
+   */
+  debug(namespace: string, message: string, ...args: unknown[]): void {
+    if (isDebugEnabled()) {
+      console.log(formatMessage(namespace, message), ...args);
+    }
+  },
+
+  /**
+   * Info log - always shown
+   */
+  info(namespace: string, message: string, ...args: unknown[]): void {
+    console.info(formatMessage(namespace, message), ...args);
+  },
+
+  /**
+   * Warning log - always shown
+   */
+  warn(namespace: string, message: string, ...args: unknown[]): void {
+    console.warn(formatMessage(namespace, message), ...args);
+  },
+
+  /**
+   * Error log - always shown
+   */
+  error(namespace: string, message: string, ...args: unknown[]): void {
+    console.error(formatMessage(namespace, message), ...args);
+  },
+};
+
+/**
+ * Create a namespaced logger for a specific module
+ */
+export const createLogger = (namespace: string) => ({
+  debug: (message: string, ...args: unknown[]) => logger.debug(namespace, message, ...args),
+  info: (message: string, ...args: unknown[]) => logger.info(namespace, message, ...args),
+  warn: (message: string, ...args: unknown[]) => logger.warn(namespace, message, ...args),
+  error: (message: string, ...args: unknown[]) => logger.error(namespace, message, ...args),
+});

package/src/utils/utils.md

@@ -0,0 +1,199 @@
+# Utils Module
+
+Common utility functions for formatting, data manipulation, and function control.
+
+## Installation
+
+```typescript
+import { 
+  logger,
+  createLogger,
+  formatDate,
+  truncateText,
+  groupBy,
+  debounce,
+  throttle,
+} from '@htlkg/core/utils';
+```
+
+## Logger
+
+Debug-aware logging utility.
+
+### Basic Usage
+
+```typescript
+import { logger } from '@htlkg/core/utils';
+
+logger.debug('namespace', 'Debug message', { data });  // Only when DEBUG=true
+logger.info('namespace', 'Info message');              // Always shown
+logger.warn('namespace', 'Warning message');           // Always shown
+logger.error('namespace', 'Error message', error);     // Always shown
+```
+
+### Namespaced Logger
+
+```typescript
+import { createLogger } from '@htlkg/core/utils';
+
+const log = createLogger('my-module');
+
+log.debug('Processing started');
+log.info('Operation complete');
+log.warn('Deprecated feature used');
+log.error('Operation failed', error);
+```
+
+### Enabling Debug Logs
+
+```bash
+# Node.js
+DEBUG=true node app.js
+HTLKG_DEBUG=true node app.js
+
+# Vite (in .env)
+DEBUG=true
+HTLKG_DEBUG=true
+```
+
+## formatDate
+
+Format dates with locale support.
+
+```typescript
+import { formatDate } from '@htlkg/core/utils';
+
+formatDate(new Date());
+// "Dec 30, 2024"
+
+formatDate('2024-01-15', 'es-ES');
+// "15 ene 2024"
+
+formatDate(1704067200000, 'en-US', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+});
+// "January 1, 2024, 12:00 AM"
+```
+
+### Parameters
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `date` | `Date \| string \| number` | - | Date to format |
+| `locale` | `string` | `'en-US'` | Locale string |
+| `options` | `Intl.DateTimeFormatOptions` | `{ year, month, day }` | Format options |
+
+## truncateText
+
+Truncate text with ellipsis.
+
+```typescript
+import { truncateText } from '@htlkg/core/utils';
+
+truncateText('Hello World', 8);
+// "Hello..."
+
+truncateText('Short', 10);
+// "Short"
+
+truncateText('Long text here', 10, ' →');
+// "Long text →"
+```
+
+### Parameters
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `text` | `string` | - | Text to truncate |
+| `maxLength` | `number` | - | Max length including suffix |
+| `suffix` | `string` | `'...'` | Suffix to append |
+
+## groupBy
+
+Group array items by a key.
+
+```typescript
+import { groupBy } from '@htlkg/core/utils';
+
+const users = [
+  { name: 'Alice', role: 'admin' },
+  { name: 'Bob', role: 'user' },
+  { name: 'Carol', role: 'admin' },
+];
+
+groupBy(users, user => user.role);
+// {
+//   admin: [{ name: 'Alice', ... }, { name: 'Carol', ... }],
+//   user: [{ name: 'Bob', ... }]
+// }
+
+// Group by numeric key
+const items = [
+  { id: 1, category: 10 },
+  { id: 2, category: 20 },
+  { id: 3, category: 10 },
+];
+
+groupBy(items, item => item.category);
+// { 10: [...], 20: [...] }
+```
+
+## debounce
+
+Delay function execution until after a pause in calls.
+
+```typescript
+import { debounce } from '@htlkg/core/utils';
+
+const search = debounce((query: string) => {
+  console.log('Searching:', query);
+}, 300);
+
+// Rapid calls
+search('h');
+search('he');
+search('hel');
+search('hello');
+// Only logs "Searching: hello" after 300ms pause
+```
+
+### Use Cases
+
+- Search input handlers
+- Window resize handlers
+- Form auto-save
+
+## throttle
+
+Limit function execution to once per time period.
+
+```typescript
+import { throttle } from '@htlkg/core/utils';
+
+const handleScroll = throttle(() => {
+  console.log('Scroll position:', window.scrollY);
+}, 100);
+
+window.addEventListener('scroll', handleScroll);
+// Logs at most once every 100ms during scrolling
+```
+
+### Use Cases
+
+- Scroll event handlers
+- Mouse move handlers
+- API rate limiting
+
+## Comparison: debounce vs throttle
+
+| Scenario | debounce | throttle |
+|----------|----------|----------|
+| Search input | ✓ Wait for typing pause | ✗ |
+| Scroll tracking | ✗ | ✓ Regular updates |
+| Window resize | ✓ Final size only | ✗ |
+| Button spam prevention | ✗ | ✓ First click works |
+| Auto-save | ✓ After editing stops | ✗ |

package/src/workspace.property.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Feature: htlkg-modular-architecture, Property 2: Workspace dependencies resolve correctly
+ * 
+ * This test validates that workspace dependencies resolve correctly across all modules.
+ * For any module that depends on another workspace module, importing from the dependency
+ * should resolve to the local workspace package, not an external npm package.
+ */
+
+import { describe, it, expect } from "vitest";
+import fc from "fast-check";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get the workspace root (shared/)
+const workspaceRoot = join(__dirname, "../../..");
+
+interface PackageJson {
+	name: string;
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+}
+
+// Helper to read package.json
+function readPackageJson(packagePath: string): PackageJson {
+	const pkgPath = join(workspaceRoot, packagePath, "package.json");
+	if (!existsSync(pkgPath)) {
+		throw new Error(`Package.json not found at ${pkgPath}`);
+	}
+	return JSON.parse(readFileSync(pkgPath, "utf-8"));
+}
+
+// Helper to check if a dependency uses workspace protocol
+function usesWorkspaceProtocol(version: string): boolean {
+	return version.startsWith("workspace:");
+}
+
+// Get all workspace packages
+const workspacePackages = [
+	"packages/core",
+	"packages/data",
+	"packages/components",
+	"packages/astro",
+];
+
+describe("Workspace Structure Property Tests", () => {
+	/**
+	 * Property 2: Workspace dependencies resolve correctly
+	 * Validates: Requirements 1.4, 7.1, 7.2, 7.3, 7.4
+	 * 
+	 * Note: Packages use version numbers (e.g., ^0.0.1) instead of workspace protocol
+	 * because they are published to npm. This is valid for published packages.
+	 */
+	it("should have valid internal dependencies", () => {
+		// For each package in the workspace
+		for (const packagePath of workspacePackages) {
+			const pkg = readPackageJson(packagePath);
+
+			// Check all dependencies
+			const allDeps = {
+				...pkg.dependencies,
+				...pkg.devDependencies,
+			};
+
+			// For each dependency
+			for (const [depName, depVersion] of Object.entries(allDeps)) {
+				// If it's an @htlkg package (internal workspace package)
+				if (depName.startsWith("@htlkg/")) {
+					// It should have a valid version (either workspace protocol or semver)
+					const isValid = usesWorkspaceProtocol(depVersion) || /^\^?\d+\.\d+\.\d+/.test(depVersion);
+					expect(
+						isValid,
+						`Package ${pkg.name} should have valid version for ${depName}, but got ${depVersion}`,
+					).toBe(true);
+				}
+			}
+		}
+	});
+
+	it("should have valid package structure for all workspace packages", () => {
+		for (const packagePath of workspacePackages) {
+			const pkg = readPackageJson(packagePath);
+
+			// Each package should have a name
+			expect(pkg.name).toBeDefined();
+			expect(pkg.name).toMatch(/^@htlkg\//);
+
+			// Each package should have a src directory
+			const srcPath = join(workspaceRoot, packagePath, "src");
+			expect(
+				existsSync(srcPath),
+				`Package ${pkg.name} should have a src directory`,
+			).toBe(true);
+
+			// Each package should have an index.ts
+			const indexPath = join(srcPath, "index.ts");
+			expect(
+				existsSync(indexPath),
+				`Package ${pkg.name} should have an index.ts file`,
+			).toBe(true);
+		}
+	});
+
+	it("should have correct TypeScript configuration for all packages", () => {
+		for (const packagePath of workspacePackages) {
+			const tsconfigPath = join(workspaceRoot, packagePath, "tsconfig.json");
+
+			expect(
+				existsSync(tsconfigPath),
+				`Package at ${packagePath} should have a tsconfig.json`,
+			).toBe(true);
+
+			const tsconfig = JSON.parse(readFileSync(tsconfigPath, "utf-8"));
+
+			// Should have compiler options
+			expect(tsconfig.compilerOptions).toBeDefined();
+
+			// Should have proper output directory (if it has one)
+			if (tsconfig.compilerOptions.outDir) {
+				expect(tsconfig.compilerOptions.outDir).toMatch(/\.\/dist|\.\/build/);
+			}
+		}
+	});
+
+	it("should have correct build configuration for all packages", () => {
+		for (const packagePath of workspacePackages) {
+			const pkg = readPackageJson(packagePath);
+
+			// Should have build script
+			expect(pkg.scripts?.build, `Package ${pkg.name} should have a build script`).toBeDefined();
+
+			// Should have dev script
+			expect(pkg.scripts?.dev, `Package ${pkg.name} should have a dev script`).toBeDefined();
+
+			// Should have test scripts
+			expect(pkg.scripts?.test, `Package ${pkg.name} should have a test script`).toBeDefined();
+		}
+	});
+
+	/**
+	 * Property-based test: Dependency graph should be acyclic
+	 * This ensures no circular dependencies exist
+	 */
+	it("should not have circular dependencies", () => {
+		// Build dependency graph
+		const graph = new Map<string, Set<string>>();
+
+		for (const packagePath of workspacePackages) {
+			const pkg = readPackageJson(packagePath);
+			const deps = new Set<string>();
+
+			// Collect all @htlkg dependencies
+			const allDeps = {
+				...pkg.dependencies,
+				...pkg.devDependencies,
+			};
+
+			for (const depName of Object.keys(allDeps)) {
+				if (depName.startsWith("@htlkg/")) {
+					deps.add(depName);
+				}
+			}
+
+			graph.set(pkg.name, deps);
+		}
+
+		// Check for cycles using DFS
+		function hasCycle(
+			node: string,
+			visited: Set<string>,
+			recStack: Set<string>,
+		): boolean {
+			visited.add(node);
+			recStack.add(node);
+
+			const neighbors = graph.get(node) || new Set();
+			for (const neighbor of neighbors) {
+				if (!visited.has(neighbor)) {
+					if (hasCycle(neighbor, visited, recStack)) {
+						return true;
+					}
+				} else if (recStack.has(neighbor)) {
+					return true;
+				}
+			}
+
+			recStack.delete(node);
+			return false;
+		}
+
+		const visited = new Set<string>();
+		for (const node of graph.keys()) {
+			if (!visited.has(node)) {
+				const recStack = new Set<string>();
+				expect(
+					hasCycle(node, visited, recStack),
+					`Circular dependency detected starting from ${node}`,
+				).toBe(false);
+			}
+		}
+	});
+
+	/**
+	 * Property-based test: All exports should be defined
+	 */
+	it("should have all declared exports as files", () => {
+		for (const packagePath of workspacePackages) {
+			const pkg = readPackageJson(packagePath);
+
+			if (!pkg.exports) continue;
+
+			// Check each export path
+			for (const [exportKey, exportValue] of Object.entries(pkg.exports)) {
+				if (typeof exportValue === "string") {
+					// Skip wildcard exports as they represent patterns, not specific files
+					if (exportValue.includes("*")) continue;
+
+					// Simple export
+					const exportPath = join(
+						workspaceRoot,
+						packagePath,
+						exportValue.replace("./dist/", "src/").replace(".js", ".ts"),
+					);
+					expect(
+						existsSync(exportPath),
+						`Export ${exportKey} in ${pkg.name} should have corresponding source file at ${exportPath}`,
+					).toBe(true);
+				}
+			}
+		}
+	});
+});