@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.24

package/src/utils/deep-merge.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { deepMerge } from './deep-merge.ts';
+
+describe('deepMerge', () => {
+	it('should merge two objects with nested properties', () => {
+		const target = { a: 1, b: { c: 2 } };
+		const source = { b: { d: 3 }, e: 4 };
+		const expected = { a: 1, b: { c: 2, d: 3 }, e: 4 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two objects with overlapping properties', () => {
+		const target = { a: 1, b: 2 };
+		const source = { b: 3, c: 4 };
+		const expected = { a: 1, b: 3, c: 4 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two objects with arrays', () => {
+		const target = { a: [1, 2], b: { c: [3, 4] } };
+		const source = { a: [5, 6], b: { c: [7, 8] } };
+		const expected = { a: [1, 2, 5, 6], b: { c: [3, 4, 7, 8] } };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two objects with nested objects', () => {
+		const target = { a: { b: 1, c: 2 }, d: 3 };
+		const source = { a: { c: 3, d: 4 }, e: 5 };
+		const expected = { a: { b: 1, c: 3, d: 4 }, d: 3, e: 5 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should overwrite non-object properties in the target', () => {
+		const target = { a: 1, b: 2 };
+		const source = { a: 3, c: 4 };
+		const expected = { a: 3, b: 2, c: 4 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should add properties from the source that are not in the target', () => {
+		const target = { a: 1 };
+		const source = { b: 2 };
+		const expected = { a: 1, b: 2 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should return an empty object when both inputs are empty', () => {
+		const target = {};
+		const source = {};
+		const expected = {};
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should ignore properties in the source that are undefined', () => {
+		const target = { a: 1, b: 2 };
+		const source = { a: undefined, c: 3 } as Partial<typeof target>;
+		const expected = { a: 1, b: 2, c: 3 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge dependencies', () => {
+		const depsA = {
+			stylesheets: ['/components/radiant-counter/radiant-counter.css'],
+			scripts: ['/components/radiant-counter/radiant-counter.script.ts'],
+		};
+
+		const depsB = {
+			stylesheets: [
+				'/layouts/docs-layout/docs-layout.css',
+				'/layouts/base-layout/base-layout.css',
+				'/components/header/header.css',
+				'/components/navigation/navigation.css',
+				'/components/logo/logo.css',
+				'/components/code-block/code-block.css',
+			],
+			scripts: ['/layouts/base-layout/base-layout.script.ts'],
+		};
+
+		const expected = {
+			stylesheets: [
+				'/components/radiant-counter/radiant-counter.css',
+				'/layouts/docs-layout/docs-layout.css',
+				'/layouts/base-layout/base-layout.css',
+				'/components/header/header.css',
+				'/components/navigation/navigation.css',
+				'/components/logo/logo.css',
+				'/components/code-block/code-block.css',
+			],
+			scripts: [
+				'/components/radiant-counter/radiant-counter.script.ts',
+				'/layouts/base-layout/base-layout.script.ts',
+			],
+		};
+
+		const result = deepMerge(depsA, depsB);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two arrays', () => {
+		const target = [1, 2, 3];
+		const source = [4, 5, 6];
+		const expected = [1, 2, 3, 4, 5, 6];
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+});

package/src/utils/deep-merge.ts

@@ -0,0 +1,47 @@
+/**
+ * This module contains a simple utility function to merge two objects deeply
+ * @module
+ */
+
+function isObject(item: any): item is Record<string, unknown> {
+	return item && typeof item === 'object' && !Array.isArray(item);
+}
+
+function isArray(item: any): item is unknown[] {
+	return Array.isArray(item);
+}
+
+/**
+ * Deeply merges two objects or arrays
+ * @function deepMerge
+ * @template T - Type of target object
+ * @template U - Type of source object
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns A new object with merged properties
+ */
+export function deepMerge<T, U>(target: T, source: U): T & U {
+	if (isArray(target) && isArray(source)) {
+		return [...target, ...source] as T & U;
+	}
+
+	if (!isObject(target) || !isObject(source)) {
+		return source as T & U;
+	}
+
+	const output = Object.assign({}, target) as T & U;
+	for (const key in source) {
+		if (isObject((source as any)[key])) {
+			if (!(target as any)[key]) {
+				Object.assign(output as object, { [key]: (source as any)[key] });
+			} else {
+				output[key as keyof T] = deepMerge((target as any)[key], (source as any)[key]);
+			}
+		} else if (isArray((source as any)[key])) {
+			output[key as keyof T] = [...((target as any)[key] || []), ...(source as any)[key]] as (T & U)[keyof T];
+		} else if ((source as any)[key] !== undefined) {
+			Object.assign(output as object, { [key]: (source as any)[key] });
+		}
+	}
+	return output;
+}

package/src/utils/hash.ts

@@ -0,0 +1,5 @@
+import { runtimeHash } from './runtime.ts';
+
+export const rapidhash = (content: string | Buffer<ArrayBufferLike>): number | bigint => {
+	return runtimeHash(content);
+};

package/src/utils/html-escaping.ts

@@ -0,0 +1,9 @@
+/**
+ * Escapes a string for safe use inside a double-quoted HTML attribute value.
+ *
+ * @param value Raw attribute value.
+ * @returns Escaped attribute-safe string.
+ */
+export function escapeHtmlAttribute(value: string): string {
+	return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}

package/src/utils/invariant.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'vitest';
+import { invariant } from './invariant.ts';
+
+describe('invariant', () => {
+	test('should not throw an error when the condition is true', () => {
+		expect(() => {
+			invariant(true);
+		}).not.toThrow();
+	});
+
+	test('should throw an error with the default message when the condition is false', () => {
+		expect(() => {
+			invariant(false);
+		}).toThrowError('[ecopages] An error occurred');
+	});
+
+	test('should throw an error with the provided message when the condition is false', () => {
+		expect(() => {
+			invariant(false, 'Custom error message');
+		}).toThrowError('[ecopages] Custom error message');
+	});
+});

package/src/utils/invariant.ts

@@ -0,0 +1,15 @@
+/**
+ * This module contains a simple utility invariant function that throws an error if the condition is not met
+ * @module
+ */
+
+const prefix = '[ecopages]';
+
+export function invariant(condition: boolean, message?: string): asserts condition {
+	if (condition) {
+		return;
+	}
+
+	const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
+	throw new Error(value);
+}

package/src/utils/locals-utils.ts

@@ -0,0 +1,37 @@
+import type { ApiHandlerContext } from '../types/public-types.ts';
+
+/**
+ * Creates a require function for validating and retrieving request locals.
+ * Supports both single key access and multiple keys with type safety.
+ *
+ * @param getLocals - Function that returns the current locals object
+ * @returns A require function that throws the onMissing response if keys are not found
+ *
+ * @example
+ * ```ts
+ * const require = createRequire(() => context.locals);
+ * const userId = require('userId', () => new Response('Unauthorized', { status: 401 }));
+ * ```
+ */
+export function createRequire(getLocals: () => Record<string, unknown>): ApiHandlerContext['require'] {
+	return (keyOrKeys: string | readonly string[], onMissing: () => Response) => {
+		const locals = getLocals();
+		if (Array.isArray(keyOrKeys)) {
+			const result: Record<string, unknown> = {};
+			for (const key of keyOrKeys) {
+				const value = locals[key];
+				if (value === undefined || value === null) {
+					throw onMissing();
+				}
+				result[key] = value;
+			}
+			return result;
+		}
+
+		const value = locals[keyOrKeys as string];
+		if (value === undefined || value === null) {
+			throw onMissing();
+		}
+		return value;
+	};
+}

package/src/utils/parse-cli-args.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { parseCliArgs } from './parse-cli-args.ts';
+
+const originalArgv = [...process.argv];
+const originalNodeEnv = process.env.NODE_ENV;
+const originalEmbeddedRuntime = process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME;
+
+describe('parseCliArgs', () => {
+	afterEach(() => {
+		process.argv = [...originalArgv];
+
+		if (originalNodeEnv === undefined) {
+			delete process.env.NODE_ENV;
+		} else {
+			process.env.NODE_ENV = originalNodeEnv;
+		}
+
+		if (originalEmbeddedRuntime === undefined) {
+			delete process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME;
+		} else {
+			process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME = originalEmbeddedRuntime;
+		}
+	});
+
+	it('treats embedded development runtimes as dev mode', () => {
+		process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME = 'true';
+		process.env.NODE_ENV = 'development';
+
+		expect(parseCliArgs()).toEqual({
+			preview: false,
+			build: false,
+			start: false,
+			dev: true,
+			port: undefined,
+			hostname: undefined,
+			reactFastRefresh: undefined,
+		});
+	});
+
+	it('keeps embedded production runtimes in start mode', () => {
+		process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME = 'true';
+		process.env.NODE_ENV = 'production';
+
+		expect(parseCliArgs()).toEqual({
+			preview: false,
+			build: false,
+			start: true,
+			dev: false,
+			port: undefined,
+			hostname: undefined,
+			reactFastRefresh: undefined,
+		});
+	});
+
+	it('supports explicit embedded runtime bootstrap without mutating process env', () => {
+		delete process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME;
+		process.env.NODE_ENV = 'development';
+
+		expect(parseCliArgs({ embeddedRuntime: true })).toEqual({
+			preview: false,
+			build: false,
+			start: false,
+			dev: true,
+			port: undefined,
+			hostname: undefined,
+			reactFastRefresh: undefined,
+		});
+	});
+});

package/src/utils/parse-cli-args.ts

@@ -0,0 +1,105 @@
+import { parseArgs } from 'node:util';
+import { getRuntimeArgv } from './runtime.ts';
+
+function getEmbeddedRuntimeCommandOptions(): ReturnParseCliArgs {
+	const isDevelopment = process.env.NODE_ENV === 'development';
+
+	return {
+		preview: false,
+		build: false,
+		start: !isDevelopment,
+		dev: isDevelopment,
+		port: undefined,
+		hostname: undefined,
+		reactFastRefresh: undefined,
+	};
+}
+
+/**
+ * Parsed command line arguments for the Ecopages server.
+ * @property preview - Whether to run in preview mode
+ * @property build - Whether to run a static build
+ * @property start - Whether to start the server
+ * @property dev - Whether to run in development mode
+ * @property port - Optional port number
+ * @property hostname - Optional hostname
+ * @property reactFastRefresh - Whether React Fast Refresh is enabled
+ */
+export type ReturnParseCliArgs = {
+	preview: boolean;
+	build: boolean;
+	start: boolean;
+	dev: boolean;
+	port?: number;
+	hostname?: string;
+	reactFastRefresh?: boolean;
+};
+
+const ECOPAGES_BIN_FILES = ['ecopages.ts', 'ecopages.js', 'cli.js'];
+
+const ECOPAGES_AVAILABLE_COMMANDS = ['dev', 'build', 'start', 'preview'];
+
+export type ParseCliArgsOptions = {
+	embeddedRuntime?: boolean;
+};
+
+/**
+ * Parses command line arguments for the server.
+ * It returns {@link ReturnParseCliArgs}
+ */
+export function parseCliArgs(options: ParseCliArgsOptions = {}): ReturnParseCliArgs {
+	if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === 'true') {
+		return getEmbeddedRuntimeCommandOptions();
+	}
+
+	const runtimeArgv = getRuntimeArgv();
+
+	const { values } = parseArgs({
+		args: runtimeArgv,
+		options: {
+			dev: { type: 'boolean' },
+			preview: { type: 'boolean' },
+			build: { type: 'boolean' },
+			port: { type: 'string' },
+			hostname: { type: 'string' },
+			'react-fast-refresh': { type: 'boolean' },
+		},
+		allowPositionals: true,
+	});
+
+	let command = '';
+	const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
+
+	const isAvailableCommand = ecopagesIndex !== -1;
+
+	if (isAvailableCommand) {
+		command =
+			ecopagesIndex < runtimeArgv.length - 1 &&
+			ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
+				return runtimeArgv[ecopagesIndex + 1] === cmd;
+			})
+				? runtimeArgv[ecopagesIndex + 1]
+				: 'start';
+	}
+
+	const isStartCommand = command === 'start' || (!values.dev && !values.build && !values.preview);
+	const isDevCommand = command === 'dev' || !!values.dev;
+	const isBuildCommand = command === 'build' || !!values.build;
+	const isPreviewCommand = command === 'preview' || !!values.preview;
+
+	const parsedCommandOptions = {
+		preview: isPreviewCommand,
+		build: isBuildCommand,
+		start: isStartCommand,
+		dev: isDevCommand,
+		port: values.port ? Number(values.port) : undefined,
+		hostname: values.hostname,
+		reactFastRefresh: values['react-fast-refresh'],
+	};
+
+	if (!process.env.NODE_ENV) {
+		process.env.NODE_ENV = isDevCommand ? 'development' : 'production';
+	}
+
+	return parsedCommandOptions;
+}

package/src/utils/path-utils.module.ts

@@ -0,0 +1,14 @@
+import path from 'node:path';
+
+function getEcoTemplateExtension(filePath: string) {
+	const { name, ext } = path.parse(filePath);
+	const nameParts = name.split('.');
+	const descriptor = nameParts.length > 1 ? nameParts.pop() : undefined;
+	const templateExtension = descriptor ? `.${descriptor}${ext}` : ext;
+
+	return templateExtension;
+}
+
+export const PathUtils = {
+	getEcoTemplateExtension,
+};

package/src/utils/path-utils.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'vitest';
+import { PathUtils } from './path-utils.module.ts';
+
+describe('PathUtils', () => {
+	test.each([
+		['packages/core/src/utils/file-name-analyzer.ts', '.ts'],
+		['packages/playground/src/pages/blog/author/%5Bid%5D.kita.tsx', '.kita.tsx'],
+		['packages/core/src/component-utils/deps-manager.ts', '.ts'],
+		['/packages/core/src/plugins/build-html-pages/build-html-pages.plugin.ts', '.plugin.ts'],
+		['packages/core/src/ecopages.fake.descriptor.ts', '.descriptor.ts'],
+	])('getEcoTemplateExtension: %p should return %p', (filePath, expected) => {
+		const result = PathUtils.getEcoTemplateExtension(filePath);
+		expect(result).toBe(expected);
+	});
+});

package/src/utils/resolve-work-dir.ts

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../config/constants.ts';
+
+type InternalPathConfig = {
+	rootDir?: string;
+	workDir?: string;
+	absolutePaths?: {
+		workDir?: string;
+		distDir?: string;
+	};
+};
+
+function isInsideNodeModules(directory: string): boolean {
+	return path.normalize(directory).split(path.sep).includes('node_modules');
+}
+
+export function resolveInternalWorkDir(appConfig: InternalPathConfig): string {
+	if (appConfig.absolutePaths?.workDir) {
+		return appConfig.absolutePaths.workDir;
+	}
+
+	if (appConfig.rootDir) {
+		return path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+	}
+
+	if (appConfig.workDir) {
+		return appConfig.workDir;
+	}
+
+	return DEFAULT_ECOPAGES_WORK_DIR;
+}
+
+export function resolveInternalExecutionDir(appConfig: InternalPathConfig): string {
+	const workDir = resolveInternalWorkDir(appConfig);
+
+	if (!isInsideNodeModules(workDir)) {
+		return workDir;
+	}
+
+	if (appConfig.rootDir) {
+		return path.join(appConfig.rootDir, DEFAULT_ECOPAGES_WORK_DIR);
+	}
+
+	return DEFAULT_ECOPAGES_WORK_DIR;
+}

package/src/utils/runtime.ts

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+
+export const RUNTIME_ERRORS = {
+	BUN_RUNTIME_REQUIRED: 'Bun runtime is required',
+} as const;
+
+type RuntimeBun = typeof Bun;
+
+export function getBunRuntime(): RuntimeBun | undefined {
+	return (globalThis as { Bun?: RuntimeBun }).Bun;
+}
+
+export function getRequiredBunRuntime(): RuntimeBun {
+	const bun = getBunRuntime();
+
+	if (!bun) {
+		throw new Error(RUNTIME_ERRORS.BUN_RUNTIME_REQUIRED);
+	}
+
+	return bun;
+}
+
+export function getRuntimeArgv(): string[] {
+	return process.argv;
+}
+
+export function isDevelopmentRuntime(): boolean {
+	return process.env.NODE_ENV === 'development';
+}
+
+export function isProductionRuntime(): boolean {
+	return process.env.NODE_ENV === 'production';
+}
+
+export function runtimeHash(content: string | Buffer<ArrayBufferLike>): number | bigint {
+	const bun = getBunRuntime();
+
+	if (bun) {
+		return bun.hash(content);
+	}
+
+	const hex = createHash('sha256').update(content).digest('hex').slice(0, 16);
+	return BigInt(`0x${hex}`);
+}

package/src/utils/server-utils.module.ts

@@ -0,0 +1,67 @@
+const ContentTypeMap = new Map<string, string>([
+	['jpg', 'image/jpeg'],
+	['jpeg', 'image/jpeg'],
+	['png', 'image/png'],
+	['gif', 'image/gif'],
+	['bmp', 'image/bmp'],
+	['svg', 'image/svg+xml'],
+	['tiff', 'image/tiff'],
+	['webp', 'image/webp'],
+	['avif', 'image/avif'],
+	['ico', 'image/x-icon'],
+	['mp3', 'audio/mpeg'],
+	['ogg', 'audio/ogg'],
+	['wav', 'audio/wav'],
+	['mp4', 'video/mp4'],
+	['webm', 'video/webm'],
+	['ogv', 'video/ogg'],
+	['mov', 'video/quicktime'],
+	['txt', 'text/plain'],
+	['html', 'text/html'],
+	['css', 'text/css'],
+	['js', 'text/javascript'],
+	['mjs', 'text/javascript'],
+	['json', 'application/json'],
+	['map', 'application/json'],
+	['xml', 'application/xml'],
+	['webmanifest', 'application/manifest+json'],
+	['wasm', 'application/wasm'],
+	['csv', 'text/csv'],
+	['ttf', 'font/ttf'],
+	['woff', 'font/woff'],
+	['woff2', 'font/woff2'],
+	['otf', 'font/otf'],
+	['eot', 'application/vnd.ms-fontobject'],
+	['gz', 'application/x-gzip'],
+	['zip', 'application/zip'],
+	['pdf', 'application/pdf'],
+	['doc', 'application/msword'],
+]);
+
+/**
+ * Get the content type of a file based on its extension.
+ * @param file - The file name.
+ * @returns The content type.
+ */
+export const getContentType = (file: string): string => {
+	const extension = file.split('.').pop() || 'txt';
+	return ContentTypeMap.get(extension) || 'text/plain';
+};
+
+/**
+ * Check if a file path has a known static file extension.
+ * @param file - The file name or path.
+ * @returns true if the extension is recognized.
+ */
+export const hasKnownExtension = (file: string): boolean => {
+	const extension = file.split('.').pop();
+	return extension !== undefined && ContentTypeMap.has(extension);
+};
+
+/**
+ * A module for server utilities.
+ */
+export const ServerUtils = {
+	getContentType,
+	hasKnownExtension,
+};

package/src/utils/server-utils.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'vitest';
+import { FIXTURE_APP_PROJECT_DIR } from '../../__fixtures__/constants.js';
+import { ConfigBuilder } from '../config/config-builder.ts';
+import { ServerUtils } from './server-utils.module.ts';
+
+await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+describe('ServerUtils', () => {
+	test.each([
+		['/my-file.controller.js', 'text/javascript'],
+		['/my-file.css', 'text/css'],
+		['/my-file.html', 'text/html'],
+		['/my-file.json', 'application/json'],
+		['/my-file.png', 'image/png'],
+		['/my-file.jpg', 'image/jpeg'],
+		['/my-file.jpeg', 'image/jpeg'],
+		['/my-file.svg', 'image/svg+xml'],
+		['/my-file.gif', 'image/gif'],
+		['/my-file.ico', 'image/x-icon'],
+		['/my-file', 'text/plain'],
+	])('getContentType(%p) should return %p', (filePath, expected) => {
+		expect(ServerUtils.getContentType(filePath)).toBe(expected);
+	});
+
+	test.each([
+		['/file.css', true],
+		['/file.js', true],
+		['/file.html', true],
+		['/file.txt', true],
+		['/file.png', true],
+		['/page', false],
+		['/page.', false],
+		['/page.xyz', false],
+		['/page.dd', false],
+	])('hasKnownExtension(%p) should return %p', (filePath, expected) => {
+		expect(ServerUtils.hasKnownExtension(filePath)).toBe(expected);
+	});
+});