@harperfast/harper 5.0.0-alpha.10 → 5.0.0-beta.1

package/components/Component.ts

@@ -0,0 +1,53 @@
+import { resolveBaseURLPath } from './resolveBaseURLPath';
+import { deriveCommonPatternBase } from './deriveCommonPatternBase';
+import { deriveGlobOptions, FastGlobOptions, FilesOption } from './deriveGlobOptions';
+import { scan } from 'micromatch';
+
+interface ComponentConfig {
+	files: FilesOption;
+	urlPath?: string;
+	[key: string]: unknown;
+}
+
+export type FileAndURLPathConfig = Pick<ComponentConfig, 'files' | 'urlPath'>;
+
+export class ComponentInvalidPatternError extends Error {
+	constructor(pattern: string) {
+		super(`Config 'files' option glob pattern must not contain '..' or start with '/'. Received: '${pattern}'`);
+		this.name = 'ComponentInvalidPatternError';
+	}
+}
+
+export class Component {
+	readonly globOptions: FastGlobOptions;
+	readonly baseURLPath: string;
+	readonly patternBases: string[];
+	readonly directory: string;
+	readonly name: string;
+	readonly config: ComponentConfig;
+	readonly commonPatternBase: string;
+
+	constructor(name: string, directory: string, config: ComponentConfig) {
+		this.name = name;
+		this.directory = directory;
+		this.config = config;
+
+		this.baseURLPath = resolveBaseURLPath(this.name, this.config.urlPath);
+
+		this.globOptions = deriveGlobOptions(this.config.files);
+		this.globOptions.source = this.globOptions.source.map((pattern) => {
+			if (pattern.includes('..') || pattern.startsWith('/')) {
+				throw new ComponentInvalidPatternError(pattern);
+			}
+
+			if (pattern === '.' || pattern === './') {
+				return '**/*';
+			}
+
+			return pattern;
+		});
+
+		this.patternBases = this.globOptions.source.map((pattern) => scan(pattern).base);
+		this.commonPatternBase = deriveCommonPatternBase(this.patternBases);
+	}
+}

package/components/ComponentV1.ts

@@ -0,0 +1,342 @@
+import { isMainThread } from 'node:worker_threads';
+import fg from 'fast-glob';
+import { Resources } from '../resources/Resources.ts';
+import harperLogger from '../utility/logging/harper_logger.js';
+import { resolveBaseURLPath } from './resolveBaseURLPath.ts';
+import { deriveGlobOptions, FastGlobOptions, FilesOption } from './deriveGlobOptions.ts';
+import { basename, join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { deriveURLPath } from './deriveURLPath.ts';
+import { scan } from 'micromatch';
+
+interface ComponentV1Config {
+	files: string | string[] | FilesOption;
+	/** @deprecated */ path?: string;
+	urlPath?: string;
+	/** @deprecated */ root?: string;
+	[key: string]: any;
+}
+
+interface ComponentV1Module {
+	setupDirectory?: (urlPath: string, absolutePath: string, resources: Resources) => Promise<undefined | boolean>;
+	handleDirectory?: (urlPath: string, absolutePath: string, resources: Resources) => Promise<undefined | boolean>;
+	setupFile?: (contents: Buffer, urlPath: string, absolutePath: string, resources: Resources) => Promise<void>;
+	handleFile?: (contents: Buffer, urlPath: string, absolutePath: string, resources: Resources) => Promise<void>;
+}
+
+interface ComponentV1Details {
+	config: ComponentV1Config;
+	name: string;
+	directory: string;
+	module: ComponentV1Module;
+	resources: Resources;
+}
+
+export class ComponentV1 {
+	readonly config: Readonly<ComponentV1Config>;
+	readonly name: string;
+	readonly directory: string;
+	readonly module: Readonly<ComponentV1Module>;
+	readonly resources: Resources;
+	readonly globOptions: FastGlobOptions;
+	readonly patternBases: string[];
+	readonly baseURLPath: string;
+
+	constructor(options: ComponentV1Details) {
+		// TO DO: Unfortunately `readonly` is a TS only thing and doesn't actually enforce that these properties can't be modified.
+		// Freeze these things so they can't be changed. likely do this at the end of the constructor
+		this.config = options.config;
+		this.name = options.name;
+		this.directory = options.directory;
+		this.module = options.module;
+		this.resources = options.resources;
+
+		// Config option basic validation
+		if (
+			!isNonEmptyString(this.config.files) &&
+			!isArrayOfNonEmptyStrings(this.config.files) &&
+			!isObject(this.config.files)
+		) {
+			throw new InvalidFilesOptionError(this);
+		}
+
+		// Validating the `files` object
+		if (typeof this.config.files === 'object' && !Array.isArray(this.config.files)) {
+			if (
+				this.config.files.source === undefined ||
+				(!isArrayOfNonEmptyStrings(this.config.files.source) && !isNonEmptyString(this.config.files.source))
+			) {
+				throw new InvalidFilesSourceOptionError(this);
+			}
+
+			if (
+				this.config.files.only !== undefined &&
+				(typeof this.config.files.only !== 'string' ||
+					!['all', 'files', 'directories'].includes(this.config.files.only))
+			) {
+				throw new InvalidFilesOnlyOptionError(this);
+			}
+
+			if (
+				this.config.files.ignore !== undefined &&
+				!isArrayOfNonEmptyStrings(this.config.files.ignore) &&
+				!isNonEmptyString(this.config.files.ignore)
+			) {
+				throw new InvalidFileIgnoreOptionError(this);
+			}
+		}
+
+		// Validate the deprecated options too
+		if (this.config.root !== undefined && !isNonEmptyString(this.config.root)) {
+			throw new InvalidRootOptionError(this);
+		}
+
+		if (this.config.path !== undefined && !isNonEmptyString(this.config.path)) {
+			throw new InvalidPathOptionError(this);
+		}
+
+		// Handle deprecated `path` option
+		if (this.config.path) {
+			harperLogger.warn(`Resource extension 'path' option is deprecated. Please replace with 'urlPath'.`);
+			this.config.urlPath = this.config.path;
+		}
+
+		// Validate the `urlPath`
+		if (
+			this.config.urlPath !== undefined &&
+			(!isNonEmptyString(this.config.urlPath) ||
+				(typeof this.config.urlPath === 'string' && this.config.urlPath.includes('..')))
+		) {
+			throw new InvalidURLPathOptionError(this);
+		}
+
+		this.globOptions = deriveGlobOptions(this.config.files);
+		// Validate and transform glob patterns
+		this.globOptions.source = this.globOptions.source.map((pattern) => {
+			if (pattern.includes('..')) {
+				throw new InvalidGlobPattern(this, pattern);
+			}
+
+			if (pattern.startsWith('/')) {
+				harperLogger.warn(
+					`Leading '/' in 'files' glob pattern is deprecated. For backwards compatibility purposes, it is currently transformed to the relative path of the component, but in the future will result in an error. Paths are automatically derived from the root of the component directory. Please remove (e.g. '/web/*' -> 'web/*').`
+				);
+
+				pattern = pattern === '/' ? '.' : pattern.slice(1);
+			}
+
+			return pattern;
+		});
+		this.patternBases = this.globOptions.source.map((pattern) => scan(pattern).base);
+		this.baseURLPath = resolveBaseURLPath(this.name, this.config.urlPath);
+	}
+}
+
+export class ComponentV1ProcessingError extends Error {
+	constructor(message: string, component: ComponentV1Details) {
+		super(`Component ${component.name} (from ${basename(component.directory)}) ${message}`);
+	}
+}
+
+export class InvalidFilesOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(`'files' option must be a non-empty string, an array of non-empty strings, or an object.`, component);
+	}
+}
+
+export class InvalidFilesSourceOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(`'files' object must have a non-empty 'source' property.`, component);
+	}
+}
+
+export class InvalidFilesOnlyOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(`'files.only' option must be one of 'all', 'files', or 'directories'.`, component);
+	}
+}
+
+export class InvalidFileIgnoreOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(`'files.ignore' option must be a non-empty string or an array of non-empty strings.`, component);
+	}
+}
+
+export class InvalidGlobPattern extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details, pattern: string) {
+		super(`'files' glob pattern must not contain '..'. Received: '${pattern}'`, component);
+	}
+}
+
+export class InvalidRootOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(
+			`deprecated 'root' option must be a non-empty string. Consider removing and updating 'files' glob pattern instead.`,
+			component
+		);
+	}
+}
+
+export class InvalidRootOptionUseError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(
+			`the 'root' option is deprecated and only supported if 'files' is a singular, non-empty string. Please remove the 'root' option and modify the 'files' glob pattern instead.`,
+			component
+		);
+	}
+}
+
+export class InvalidPathOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(`deprecated 'path' option must be a non-empty string. Consider replacing with 'urlPath'.`, component);
+	}
+}
+
+export class InvalidURLPathOptionError extends ComponentV1ProcessingError {
+	constructor(component: ComponentV1Details) {
+		super(`'urlPath' option must be a non-empty string that must not contain '..'.`, component);
+	}
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === 'string' && value.trim() !== '';
+}
+
+function isArrayOfNonEmptyStrings(value: unknown): value is string[] {
+	return Array.isArray(value) && value.length !== 0 && value.every((item) => isNonEmptyString(item));
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+async function handleRoots(component: ComponentV1) {
+	if (component.config.root) {
+		harperLogger.warn(
+			`Resource extension 'root' option is deprecated. Due to backwards compatibility reasons it does not act as assumed. The glob pattern will always be evaluated from the component directory root. The option is only used for the initial root directory handling. Please remove and modify the 'files' glob pattern instead.`
+		);
+	}
+
+	// For backwards compatibility, we need to evaluate the root path via the existing logic. This is only valid if `root` is defined, and `files` is a strings that doesn't contain `**/*`,
+	// And if that existing logic does not produce a reasonable root path to evaluate, we can consider the configure "new" and evaluate it based on a new process
+
+	let rootPaths: string[] = [];
+
+	if (component.config.root && typeof component.config.files !== 'string') {
+		throw new InvalidRootOptionUseError(component);
+	}
+
+	// This starts old root handling
+	let rootPath = component.config.root;
+
+	if (rootPath) {
+		// trim any leading slashes
+		if (rootPath.startsWith('/')) {
+			rootPath = rootPath.slice(1);
+		}
+		// add a trailing slash if it doesn't exist
+		if (!rootPath.endsWith('/')) {
+			rootPath += '/';
+		}
+	}
+
+	const pattern = component.config.files;
+
+	// This is still old root handling logic - operate only a singular pattern
+	if (typeof pattern === 'string' && !pattern.includes('**/*')) {
+		if (pattern.indexOf('/*') > -1) {
+			rootPath = pattern.slice(0, pattern.indexOf('/*') + 1);
+		} else if (pattern.indexOf('/') > -1) {
+			rootPath = pattern.slice(0, pattern.lastIndexOf('/') + 1);
+		}
+	}
+
+	if (rootPath) rootPaths.push(rootPath);
+
+	// If old handling did not result in a root path, now use the patternRoots derived from the processed glob patterns
+	if (rootPaths.length === 0) {
+		// Return early if we are only processing files
+		if (isObject(component.config.files) && component.config.files.only === 'files') {
+			return false;
+		}
+
+		rootPaths = component.patternBases;
+	}
+
+	let hasFunctionality: boolean | undefined = false;
+
+	for (const rootPath of rootPaths) {
+		const rootPathAbsolute = join(component.directory, rootPath);
+
+		if (isMainThread && component.module.setupDirectory) {
+			hasFunctionality = await component.module.setupDirectory(
+				component.baseURLPath,
+				rootPathAbsolute,
+				component.resources
+			);
+		}
+		if (component.resources.isWorker && component.module.handleDirectory) {
+			hasFunctionality = await component.module.handleDirectory(
+				component.baseURLPath,
+				rootPathAbsolute,
+				component.resources
+			);
+		}
+	}
+
+	return hasFunctionality;
+}
+
+/**
+ * Process a Resource Extension component by evaluating the files glob pattern
+ * and then calling the appropriate setup/handle functions.
+ */
+export async function processResourceExtensionComponent(component: ComponentV1) {
+	let hasFunctionality: boolean | undefined = false;
+
+	hasFunctionality = await handleRoots(component);
+
+	// Return early if roots were functional
+	if (hasFunctionality) return hasFunctionality;
+
+	const matches = await fg(component.globOptions.source, {
+		cwd: component.directory,
+		objectMode: true,
+		onlyFiles: component.globOptions.onlyFiles,
+		onlyDirectories: component.globOptions.onlyDirectories,
+		ignore: component.globOptions.ignore,
+	});
+
+	for (const entry of matches) {
+		const absolutePath = join(component.directory, entry.path);
+
+		if (entry.dirent.isDirectory()) {
+			const urlPath = deriveURLPath(component, entry.path, 'directory');
+			if (isMainThread && component.module.setupDirectory) {
+				await component.module.setupDirectory(urlPath, absolutePath, component.resources);
+				hasFunctionality = true;
+			}
+			if (component.resources.isWorker && component.module.handleDirectory) {
+				await component.module.handleDirectory(urlPath, absolutePath, component.resources);
+				hasFunctionality = true;
+			}
+		} else if (entry.dirent.isFile()) {
+			const urlPath = deriveURLPath(component, entry.path, 'file');
+			const contents = await readFile(absolutePath);
+			if (isMainThread && component.module.setupFile) {
+				await component.module.setupFile(contents, urlPath, absolutePath, component.resources);
+				hasFunctionality = true;
+			} else if (component.resources.isWorker && component.module.handleFile) {
+				await component.module.handleFile(contents, urlPath, absolutePath, component.resources);
+				hasFunctionality = true;
+			}
+		} else {
+			harperLogger.error(
+				`Entry received from glob pattern match for component ${component.name} is neither a file nor a directory:`,
+				entry
+			);
+		}
+	}
+
+	return hasFunctionality;
+}

package/components/DEFAULT_CONFIG.ts

@@ -0,0 +1,18 @@
+export const DEFAULT_CONFIG = {
+	rest: true,
+	graphqlSchema: {
+		files: '*.graphql',
+	},
+	roles: {
+		files: 'roles.yaml',
+	},
+	jsResource: {
+		files: 'resources.js',
+	},
+	fastifyRoutes: {
+		files: 'routes/*.js',
+	},
+	static: {
+		files: 'web/**',
+	},
+};

package/components/EntryHandler.ts

@@ -0,0 +1,227 @@
+import { type Logger } from '../utility/logging/logger.ts';
+import { loggerWithTag } from '../utility/logging/harper_logger.js';
+import type { Stats } from 'node:fs';
+import { EventEmitter, once } from 'node:events';
+import { Component, FileAndURLPathConfig } from './Component.js';
+import chokidar, { FSWatcher, FSWatcherEventMap } from 'chokidar';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { FilesOption } from './deriveGlobOptions.js';
+import { deriveURLPath } from './deriveURLPath.js';
+import { isMatch } from 'micromatch';
+
+export interface BaseEntry {
+	stats?: Stats;
+	urlPath: string;
+	absolutePath: string;
+}
+
+export interface FileEntry extends BaseEntry {
+	contents: Buffer;
+}
+
+export interface EntryEvent extends BaseEntry {
+	eventType: string;
+	entryType: string;
+}
+
+export interface AddFileEvent extends EntryEvent, FileEntry {
+	eventType: 'add';
+	entryType: 'file';
+}
+
+export interface ChangeFileEvent extends EntryEvent, FileEntry {
+	eventType: 'change';
+	entryType: 'file';
+}
+
+export interface UnlinkFileEvent extends EntryEvent {
+	eventType: 'unlink';
+	entryType: 'file';
+}
+
+export type FileEntryEvent = AddFileEvent | ChangeFileEvent | UnlinkFileEvent;
+
+export interface AddDirectoryEvent extends EntryEvent {
+	eventType: 'addDir';
+	entryType: 'directory';
+}
+
+export interface UnlinkDirectoryEvent extends EntryEvent {
+	eventType: 'unlinkDir';
+	entryType: 'directory';
+}
+
+export type DirectoryEntryEvent = AddDirectoryEvent | UnlinkDirectoryEvent;
+
+export type onEntryEventHandler = (entry: FileEntryEvent | DirectoryEntryEvent) => void | Promise<void>;
+
+export type EntryHandlerEventMap = {
+	all: [entry: FileEntryEvent | DirectoryEntryEvent];
+	close: [];
+	error: [error: unknown];
+	ready: [];
+	initialLoadComplete: [];
+	add: [entry: AddFileEvent];
+	change: [entry: ChangeFileEvent];
+	unlink: [entry: UnlinkFileEvent];
+	addDir: [entry: AddDirectoryEvent];
+	unlinkDir: [entry: UnlinkDirectoryEvent];
+};
+
+export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
+	#component: Component;
+	#watcher?: FSWatcher;
+	#logger: Logger;
+	#pendingFileReads: Set<Promise<void>>;
+	#isInitialScanComplete: boolean;
+	ready: Promise<any[]>;
+
+	constructor(name: string, directory: string, config: FilesOption | FileAndURLPathConfig, logger?: Logger) {
+		super();
+
+		this.#component = new Component(name, directory, castConfig(config));
+		this.#logger = logger || loggerWithTag(name);
+		this.#pendingFileReads = new Set();
+		this.#isInitialScanComplete = false;
+		this.ready = once(this, 'ready');
+		this.#watch();
+	}
+
+	get name(): string {
+		return this.#component.name;
+	}
+
+	get directory(): string {
+		return this.#component.directory;
+	}
+
+	#handleAll(...[event, path, stats]: FSWatcherEventMap['all']): void {
+		if (path === '') path = '/';
+
+		if (!isMatch(path, this.#component.globOptions.source, { ignore: this.#component.globOptions.ignore })) return;
+
+		const absolutePath = join(this.directory, path);
+
+		switch (event) {
+			case 'add':
+			case 'change': {
+				const urlPath = deriveURLPath(this.#component, path, 'file');
+				const fileReadPromise = readFile(absolutePath)
+					.then((contents) => {
+						const entry: AddFileEvent | ChangeFileEvent = {
+							eventType: event,
+							entryType: 'file' as const,
+							contents,
+							stats,
+							absolutePath,
+							urlPath,
+						};
+						this.emit('all', entry);
+						this.emit(event, entry as any);
+					})
+					.finally(() => {
+						this.#pendingFileReads.delete(fileReadPromise);
+						this.#checkIfAllComplete();
+					});
+
+				this.#pendingFileReads.add(fileReadPromise);
+				break;
+			}
+			case 'unlink': {
+				const urlPath = deriveURLPath(this.#component, path, 'file');
+				const entry: UnlinkFileEvent = {
+					eventType: event,
+					entryType: 'file',
+					stats,
+					absolutePath,
+					urlPath,
+				};
+				this.emit('all', entry);
+				this.emit(event, entry);
+				break;
+			}
+			case 'addDir':
+			case 'unlinkDir': {
+				const urlPath = deriveURLPath(this.#component, path, 'directory');
+				const entry: DirectoryEntryEvent = {
+					eventType: event,
+					entryType: 'directory' as const,
+					stats,
+					absolutePath,
+					urlPath,
+				};
+				this.emit('all', entry);
+				this.emit(event, entry as any);
+				break;
+			}
+		}
+	}
+
+	#handleError(error: unknown): void {
+		this.emit('error', error);
+	}
+
+	#handleReady(): void {
+		this.#isInitialScanComplete = true;
+		if (this.#pendingFileReads.size > 0) {
+			this.#logger.debug?.(
+				`Initial scan complete, still waiting for ${this.#pendingFileReads.size} pending file reads`
+			);
+		}
+		this.#checkIfAllComplete();
+	}
+
+	#checkIfAllComplete(): void {
+		// Only emit 'ready' once the initial scan is complete AND all file reads are done
+		if (this.#isInitialScanComplete && this.#pendingFileReads.size === 0) {
+			this.emit('ready');
+		}
+	}
+
+	async #watch() {
+		await this.#watcher?.close();
+		this.#watcher = undefined;
+
+		const allowedBases = this.#component.patternBases.map((base) => join(this.#component.directory, base));
+
+		this.#watcher = chokidar
+			.watch(this.#component.commonPatternBase, {
+				cwd: this.#component.directory,
+				persistent: false,
+				ignored: (path) => {
+					const normalizedPath = path.replace(/\\/g, '/');
+					const normalizedBases = allowedBases.map((base) => base.replace(/\\/g, '/'));
+					return (
+						normalizedPath !== this.#component.directory.replace(/\\/g, '/') &&
+						normalizedBases.every((base) => !normalizedPath.startsWith(base))
+					);
+				},
+			})
+			.on('all', this.#handleAll.bind(this))
+			.on('error', this.#handleError.bind(this))
+			.on('ready', this.#handleReady.bind(this));
+
+		return this.ready;
+	}
+
+	close(): this {
+		this.#watcher?.close();
+		this.#watcher = undefined;
+
+		this.emit('close');
+		this.removeAllListeners();
+
+		return this;
+	}
+
+	update(config: FilesOption | FileAndURLPathConfig) {
+		this.#component = new Component(this.name, this.directory, castConfig(config));
+
+		return this.#watch();
+	}
+}
+
+function castConfig(config: FilesOption | FileAndURLPathConfig): FileAndURLPathConfig {
+	return typeof config === 'string' || Array.isArray(config) || !('files' in config) ? { files: config } : config;
+}

package/components/Logger.ts

@@ -0,0 +1,14 @@
+export interface Logger {
+	logLevel: string;
+
+	notify?: (...args: any[]) => void;
+	fatal?: (...args: any[]) => void;
+	error?: (...args: any[]) => void;
+	warn?: (...args: any[]) => void;
+	info?: (...args: any[]) => void;
+	debug?: (...args: any[]) => void;
+	trace?: (...args: any[]) => void;
+
+	withTag: (tag: string) => Logger;
+	loggerWithTag: (tag: string) => Logger;
+}