General Repo Updates

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Format
+9077b5b81d266818af4a25b90c78e0e7d03620a3

.github/workflows/format-check.yml

@@ -0,0 +1,28 @@
+name: Format Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  format-check:
+    name: Format Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run format check
+        run: npm run format:check

.github/workflows/integration-test.yml

@@ -29,10 +29,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'

.github/workflows/unit-test.yml

@@ -29,10 +29,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
@@ -53,4 +53,4 @@ jobs:
         run: node --enable-source-maps ./dist/bin/harperdb.js install
 
       - name: Run tests
-        run: npm run test:unit
+        run: npm run test:unit:all

CODE_OF_CONDUCT.md

@@ -1,4 +1,3 @@
-
 # Contributor Covenant 3.0 Code of Conduct
 
 ## Our Pledge
@@ -21,7 +20,6 @@ With these considerations in mind, we agree to behave mindfully toward each othe
 6. Committing to **repairing harm** when it occurs.
 7. Behaving in other ways that promote and sustain the **well-being of our community**.
 
-
 ## Restricted Behaviors
 
 We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
@@ -41,7 +39,6 @@ We agree to restrict the following behaviors in our community. Instances, threat
 3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
 4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
 
-
 ## Reporting an Issue
 
 Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
@@ -50,41 +47,37 @@ When an incident does occur, it is important to report it promptly. To report a
 
 Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
 
-
 ## Addressing and Repairing Harm
 
 If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
 
-1) Warning
-   1) Event: A violation involving a single incident or series of incidents.
-   2) Consequence: A private, written warning from the Community Moderators.
-   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
-2) Temporarily Limited Activities
-   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
-   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
-   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
-3) Temporary Suspension
-   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
-   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
-   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
-4) Permanent Ban
-   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
-   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
-   3) Repair: There is no possible repair in cases of this severity.
+1. Warning
+   1. Event: A violation involving a single incident or series of incidents.
+   2. Consequence: A private, written warning from the Community Moderators.
+   3. Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2. Temporarily Limited Activities
+   1. Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2. Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3. Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3. Temporary Suspension
+   1. Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2. Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3. Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4. Permanent Ban
+   1. Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2. Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3. Repair: There is no possible repair in cases of this severity.
 
 This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
 
-
 ## Scope
 
 This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
 
-
 ## Attribution
 
 This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
 
 Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
 
 For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).
-

CONTRIBUTING.md

@@ -15,7 +15,11 @@ Install dependencies using `npm install`
 
 Build the project using `npm run build` or `npm run build:watch` to automatically rebuild on file changes.
 
-Run tests using `npm run test:integration`. Make sure to read the [integration test instructions](./integrationTests/apiTests/README.md) for setup.
+Run integration tests using `npm run test:integration`. Make sure to read the [integration test instructions](./integrationTests/apiTests/README.md) for setup.
+
+Run unit tests using `npm run test:unit <unit-test-file>` or `npm run test:unit:all`, but make sure to build the project first since unit tests depend on the built source files.
+
+> Unit tests currently use [Mocha](https://mochajs.org/) as the test runner, but since they are implemented in TypeScript and are sometimes executing TypeScript source code, it also uses [TSX](https://tsx.is/) for compilation and execution. The npm script `test:unit` sets the appropriate env vars and mocha configuration file. Make sure that the `TSX_TSCONFIG_PATH` environment variable points to the correct `tsconfig.json` file for the unit tests (i.e. `./unitTests/tsconfig.json`) and not the root-level `tsconfig.json`.
 
 ## Repository Structure
 

README.md

@@ -1,6 +1,6 @@
 # Harper
 
-Harper is an open-source Node.js unified development platform that fuses database, cache, application, and messaging layers into one in-memory process. With Harper you can build ultra-high-performance services without boilerplate code and scale them horizontally. 
+Harper is an open-source Node.js unified development platform that fuses database, cache, application, and messaging layers into one in-memory process. With Harper you can build ultra-high-performance services without boilerplate code and scale them horizontally.
 
 **Key Features:**
 

components/DEFAULT_CONFIG.ts

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

components/EntryHandler.ts

@@ -111,7 +111,7 @@
 						urlPath,
 					};
 					this.emit('all', entry);
 					this.emit(event, entry);
 				});
 				break;
 			}
@@ -139,7 +139,7 @@
 					urlPath,
 				};
 				this.emit('all', entry);
 				this.emit(event, entry);
 				break;
 			}
 		}
@@ -165,7 +165,7 @@
 				persistent: false,
 				ignored: (path) => {
 					const normalizedPath = path.replace(/\\/g, '/');
-					const normalizedBases = allowedBases.map(base => base.replace(/\\/g, '/'));
+					const normalizedBases = allowedBases.map((base) => base.replace(/\\/g, '/'));
 					return (
 						normalizedPath !== this.#component.directory.replace(/\\/g, '/') &&
 						normalizedBases.every((base) => !normalizedPath.startsWith(base))

components/PluginModule.ts

@@ -1,7 +1,7 @@
-import { Scope } from "./Scope";
+import { Scope } from './Scope';
 
 export interface PluginModule {
 	handleApplication: (scope: Scope) => void | Promise<void>;
 	defaultTimeout?: number;
 	suppressHandleApplicationWarning?: boolean;
-}
+}

components/Scope.ts

@@ -160,7 +160,13 @@ export class Scope extends EventEmitter {
 
 	#getFilesOption(): FileAndURLPathConfig | undefined {
 		const config = this.options.getAll();
-		if (config && typeof config === 'object' && config !== null && !Array.isArray(config) && 'files' in config /*&& validate config.files*/) {
+		if (
+			config &&
+			typeof config === 'object' &&
+			config !== null &&
+			!Array.isArray(config) &&
+			'files' in config /*&& validate config.files*/
+		) {
 			return {
 				files: config.files as FilesOption,
 				urlPath: config.urlPath as string | undefined,

components/packageComponent.ts

@@ -27,7 +27,7 @@ export function packageDirectory(
 						header.mode = 0o755;
 					}
 					return header;
-				}
+				},
 			})
 			.pipe(createGzip())
 			.on('data', (chunk: Buffer) => chunks.push(chunk))

components/status/ComponentStatusRegistry.ts

@@ -6,7 +6,12 @@
  */
 
 import { ComponentStatus } from './ComponentStatus.ts';
-import { type ComponentStatusLevel, COMPONENT_STATUS_LEVELS, type AggregatedComponentStatus, type ComponentApplicationStatus } from './types.ts';
+import {
+	type ComponentStatusLevel,
+	COMPONENT_STATUS_LEVELS,
+	type AggregatedComponentStatus,
+	type ComponentApplicationStatus,
+} from './types.ts';
 import { crossThreadCollector, StatusAggregator } from './crossThread.ts';
 import { ComponentStatusOperationError } from './errors.ts';
 
@@ -206,31 +211,31 @@ export class ComponentStatusRegistry {
 		}
 
 		// Aggregate all statuses
-		const hasErrors = allStatuses.some(s => s.status === COMPONENT_STATUS_LEVELS.ERROR);
-		const hasLoading = allStatuses.some(s => s.status === COMPONENT_STATUS_LEVELS.LOADING);
+		const hasErrors = allStatuses.some((s) => s.status === COMPONENT_STATUS_LEVELS.ERROR);
+		const hasLoading = allStatuses.some((s) => s.status === COMPONENT_STATUS_LEVELS.LOADING);
 
 		const overallStatus = hasErrors
 			? COMPONENT_STATUS_LEVELS.ERROR
 			: hasLoading
-			? COMPONENT_STATUS_LEVELS.LOADING
-			: COMPONENT_STATUS_LEVELS.HEALTHY;
+				? COMPONENT_STATUS_LEVELS.LOADING
+				: COMPONENT_STATUS_LEVELS.HEALTHY;
 
 		// Show details if anything is not healthy
 		let overallMessage = 'All components loaded successfully';
 		const details: Record<string, { status: ComponentStatusLevel; message?: string }> = {};
 
 		if (hasErrors || hasLoading) {
-			const problemStatuses = allStatuses.filter(s =>
-				s.status === COMPONENT_STATUS_LEVELS.ERROR || s.status === COMPONENT_STATUS_LEVELS.LOADING
+			const problemStatuses = allStatuses.filter(
+				(s) => s.status === COMPONENT_STATUS_LEVELS.ERROR || s.status === COMPONENT_STATUS_LEVELS.LOADING
 			);
-			overallMessage = problemStatuses.map(s => `${s.key}: ${s.latestMessage || s.status}`).join('; ');
+			overallMessage = problemStatuses.map((s) => `${s.key}: ${s.latestMessage || s.status}`).join('; ');
 
 			// Include details for debugging
 			for (const status of allStatuses) {
 				if (status.status !== COMPONENT_STATUS_LEVELS.HEALTHY) {
 					details[status.key] = {
 						status: status.status,
-						message: status.latestMessage
+						message: status.latestMessage,
 					};
 				}
 			}

components/status/api.ts

@@ -1,6 +1,6 @@
 /**
  * Component Status Public API
- * 
+ *
  * This module provides the clean, simple public API for component status tracking.
  * All internal implementation details are hidden behind this interface.
  */
@@ -86,14 +86,14 @@ const builderCache = new Map<string, ComponentStatusBuilder>();
 /**
  * Get a status builder for a component
  * This is the primary API for reporting component status
- * 
+ *
  * @example
  * ```typescript
  * // Report status
  * statusForComponent('my-service').healthy('Service started');
  * statusForComponent('database').error('Connection failed', err);
  * statusForComponent('cache').warning('Memory usage high');
- * 
+ *
  * // Get status
  * const status = statusForComponent('my-service').get();
  * ```
@@ -131,7 +131,7 @@ export const lifecycle = {
 	 */
 	failed(componentName: string, error: Error | string, message?: string): void {
 		componentStatusRegistry.markFailed(componentName, error, message);
-	}
+	},
 };
 
 /**
@@ -150,4 +150,4 @@ export const STATUS = COMPONENT_STATUS_LEVELS;
  * Re-export only the types that external users need
  */
 export type { ComponentStatusLevel, AggregatedComponentStatus } from './types.ts';
-export type { ComponentStatus } from './ComponentStatus.ts';
+export type { ComponentStatus } from './ComponentStatus.ts';

components/status/internal.ts

@@ -1,6 +1,6 @@
 /**
  * Internal Component Status Exports
- * 
+ *
  * These exports are for Harper core internal use only.
  * Components should use the public API from index.ts
  */
@@ -61,5 +61,5 @@ export const query = {
 	 */
 	async allThreads() {
 		return ComponentStatusRegistry.getAggregatedFromAllThreads(componentStatusRegistry);
-	}
-};
+	},
+};

components/status/registry.ts

@@ -1,6 +1,6 @@
 /**
  * Component Status Registry Singleton
- * 
+ *
  * This module provides the global component status registry instance.
  */
 
@@ -9,4 +9,4 @@ import { ComponentStatusRegistry } from './ComponentStatusRegistry.ts';
 /**
  * Global component status registry instance
  */
-export const componentStatusRegistry = new ComponentStatusRegistry();
+export const componentStatusRegistry = new ComponentStatusRegistry();