Harvmaster/sync-server-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Establish project foundation and shared utilities

Browse Source
This commit is contained in:
Harvmaster
2026-07-27 07:07:30 +00:00
parent f465aa761b
commit 6923040484
13 changed files with 2343 additions and 902 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cspell.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"version": "0.1",
"import": ["@generalprotocols/cspell-dictionary/cspell.json"],
"words": []
"words": ["unixepoch", "kysely", "prefault", "upserting", "subsec"]
}
.gitignore
+3
View File
@@ -15,3 +15,6 @@ coverage/
*.d.ts
*.d.ts.map
*.tsbuildinfo
.env
data.db*
package-lock.json
Generated
+1869 -884
View File
File diff suppressed because it is too large Load Diff
package.json
+26 -16
View File
@@ -17,12 +17,14 @@
"scripts": {
"analyze": "tsdown --clean --no-fixed-extension --sourcemap source/index.ts && esbuild-analyzer dist/",
"build": "tsdown --clean --sourcemap source/index.ts",
"dev": "tsx watch source/index.ts",
"docs": "typedoc --hideGenerator --categorizeByGroup",
"format": "prettier --write . && eslint --fix",
"spellcheck": "cspell 'source/**' 'test/**' 'playground/**'",
"style": "eslint",
"syntax": "tsc --noEmit",
"test": "vitest --dir test/ --test-timeout=15000 --passWithNoTests --run --coverage"
"test": "vitest --dir test/ --test-timeout=15000 --passWithNoTests --run --coverage",
"test:watch": "vitest"
},
"files": [
"dist"
@@ -42,29 +44,37 @@
"xo cash"
],
"dependencies": {
"@bitauth/libauth": "^3.1.0-next.8"
"@bitauth/libauth": "^3.1.0-next.8",
"@hono/node-server": "^2.0.5",
"@xo-cash/utils": "^0.0.2-development.15512051893",
"better-sqlite3": "^12.11.1",
"debug": "^4.4.3",
"dotenv": "^17.4.2",
"hono": "^4.12.26",
"kysely": "^0.29.2",
"ws": "^8.21.0",
"zod": "^4.4.3"
},
"overrides": {
"echarts": "6.1.0"
},
"devDependencies": {
"@chalp/eslint-airbnb": "^1.3.0",
"@generalprotocols/cspell-dictionary": "^1.0.1",
"@stylistic/eslint-plugin": "^5.7.0",
"@types/node": "^25.5.0",
"@typescript-eslint/eslint-plugin": "^8.53.1",
"@typescript-eslint/parser": "^8.53.1",
"@vitest/coverage-v8": "^4.0.17",
"@types/better-sqlite3": "^7.6.13",
"@types/debug": "^4.1.13",
"@types/node": "^25.9.3",
"@types/ws": "^8.18.1",
"@vitest/coverage-v8": "^4.1.9",
"@viz-kit/esbuild-analyzer": "^1.0.0",
"@xo-cash/eslint-config": "1.0.2",
"cspell": "^9.6.0",
"eslint": "^9.39.2",
"prettier": "^3.6.2",
"tsdown": "^0.20.0-beta.4",
"typedoc": "^0.28.16",
"cspell": "^10.0.1",
"prettier": "^3.8.4",
"tsdown": "^0.22.14",
"tsx": "^4.22.4",
"typedoc": "^0.28.20",
"typedoc-plugin-coverage": "^4.0.2",
"typescript": "^5.3.2",
"typescript-eslint": "^8.53.1",
"vitest": "^4.0.17"
"typescript": "^6.0.3",
"typescript-eslint": "^8.65.0",
"vitest": "^4.1.9"
}
}
src/errors/application-error.ts
+14
View File
@@ -0,0 +1,14 @@
/** An expected application failure whose message is safe to send to clients. */
export class ApplicationError extends Error {
/**
* @param statusCode - HTTP-equivalent status returned to the client.
* @param message - Client-safe error summary.
*/
constructor(
readonly statusCode: number,
message: string,
) {
super(message);
this.name = 'ApplicationError';
}
}
src/errors/index.ts
+3
View File
@@ -0,0 +1,3 @@
export * from './application-error.ts';
export * from './unauthorized-error.ts';
export * from './utils.ts';
src/errors/unauthorized-error.ts
+10
View File
@@ -0,0 +1,10 @@
/** Authentication failure whose message is safe to return to clients. */
export class UnauthorizedError extends Error {
/**
* @param message - Client-safe unauthorized summary.
*/
constructor(message = 'Unauthorized') {
super(message);
this.name = 'UnauthorizedError';
}
}
src/errors/utils.ts
+47
View File
@@ -0,0 +1,47 @@
import { z } from 'zod';
import { UnauthorizedError } from './unauthorized-error.ts';
import { ApplicationError } from './application-error.ts';
/** Stable error payload shared by HTTP, SSE, and WebSocket. */
export type PublicError = {
/** Protocol-independent status carried by every transport. */
statusCode: number;
/** Client-safe summary which never exposes an unexpected exception. */
error: string;
/** Structured field failures supplied only for validation errors. */
details?: Array<{ path: string; message: string }>;
};
/**
* Convert application failures into the common public transport contract.
*
* @param error - Any thrown value from a route or transport boundary.
* @returns A sanitized error payload safe to encode on the wire.
*/
export const normalizePublicError = (error: unknown): PublicError => {
if (error instanceof z.ZodError) {
return {
statusCode: 400,
error: 'Validation Error',
details: error.issues.map((issue) => ({
path: issue.path.join('.'),
message: issue.message,
})),
};
}
if (error instanceof UnauthorizedError) {
return { statusCode: 401, error: error.message };
}
if (error instanceof ApplicationError) {
return { statusCode: error.statusCode, error: error.message };
}
// Unknown exceptions are logged by adapters, but their messages stay private.
return { statusCode: 500, error: 'Internal Server Error' };
};
src/services/config.ts
+127
View File
@@ -0,0 +1,127 @@
import 'dotenv/config';
import { z } from 'zod';
/**
* The configuration schema for the server.
*/
const configSchema = z.object({
/**
* The database configuration.
*/
database: z.object({
path: z.string().default('data.db'),
}),
/**
* The server configuration.
*/
server: z.object({
port: z.coerce.number().int()
.positive()
.default(3000),
host: z.string().default('0.0.0.0'),
/** Maximum encoded HTTP body or WebSocket message size in bytes. */
maxRequestBodyBytes: z.coerce
.number()
.int()
.positive()
.default(1024 * 1024),
cors: z
.object({
origin: z.string().default('*'),
methods: z.array(z.string()).default([ 'GET', 'POST', 'PUT', 'DELETE', 'OPTIONS' ]),
allowedHeaders: z.array(z.string()).default([ 'Content-Type', 'cache-control', 'X-Timestamp', 'X-PublicKey', 'X-Signature' ]),
})
.partial()
.prefault({}),
}),
/**
* The authentication configuration.
*/
auth: z
.object({
timestampWindowMs: z.coerce
.number()
.int()
.positive()
.default(5 * 60 * 1000),
})
.prefault({}),
});
/** Raw configuration object accepted before Zod parsing. */
type ConfigInput = z.input<typeof configSchema>;
/** Fully parsed and defaulted configuration shape. */
type ConfigSchema = z.output<typeof configSchema>;
/**
* Typed, validated server configuration loaded from environment or objects.
*/
export class Config {
/**
* Creates a new Config from the environment variables.
* @returns The Config.
*/
static fromEnv(): Config {
return this.from({
database: {
path: process.env.DATABASE_PATH,
},
server: {
port: process.env.SERVER_PORT,
maxRequestBodyBytes: process.env.SERVER_MAX_REQUEST_BODY_BYTES,
host: process.env.SERVER_HOST,
cors: {
origin: process.env.CORS_ORIGIN,
methods: process.env.CORS_METHODS?.split(','),
allowedHeaders: process.env.CORS_ALLOWED_HEADERS?.split(','),
},
},
auth: {
timestampWindowMs: process.env.AUTH_TIMESTAMP_WINDOW_MS ? Number(process.env.AUTH_TIMESTAMP_WINDOW_MS) : undefined,
},
});
}
/**
* Creates a new Config from a configuration object.
* @param config - The configuration object.
* @returns The Config.
*/
static from(config: ConfigInput): Config {
return new Config(configSchema.parse(config));
}
/**
* Gets the database configuration.
* @returns The database configuration.
*/
public get database(): Readonly<ConfigSchema['database']> {
return this.config.database;
}
/**
* Gets the server configuration.
* @returns The server configuration.
*/
public get server(): Readonly<ConfigSchema['server']> {
return this.config.server;
}
/**
* Gets the authentication configuration.
* @returns The authentication configuration.
*/
public get auth(): Readonly<ConfigSchema['auth']> {
return this.config.auth;
}
/**
* @param config - Parsed configuration produced by the Zod schema.
*/
private constructor(private readonly config: ConfigSchema) {}
}
src/utils/logger.ts
+66
View File
@@ -0,0 +1,66 @@
import Debug, { type Debugger } from 'debug';
type LogHandler = {
(...args: Parameters<Debugger>): void;
extend: (namespace: string) => LogHandler;
};
/**
* Declares that Logger instances may also be invoked as functions.
*/
// eslint-disable-next-line
export interface Logger {
(...args: unknown[]): void;
}
/**
* Logger class, similar to 'debug' library but you can call `instanceof Logger` to check if a value is a Logger instance.
*/
// eslint-disable-next-line
export class Logger {
public readonly namespace!: string;
private readonly handler!: LogHandler;
public constructor(namespace: string, handler: LogHandler = Debug(namespace)) {
/**
* I'm going to be honest, this file is somewhat an experiment.
* The logger from 'debug' is a fancy function with methods on it.
* I wanted to extend that functionality to support 'extend' and also determine whether the object is a Logger instance.
* This makes it trivial to perform a type check on the logger, since its no longer just a function. But, I wanted to keep the exact same API
* as debug, so this uses gross, disgusting, blasphemous prototype methods to assign a function onto this class prototype.
*/
// Make a function that just calls the 'debug' function with the given arguments
const logger = ((...args: Parameters<Debugger>): void => {
handler(...args);
}) as Logger;
// Mutate the logger function to inherit from this class.
// This allows us to use the 'instanceof' operator to check if the object is a Logger instance.
Object.setPrototypeOf(logger, new.target.prototype);
// Add the namespace and the handler to the 'logger' function we defined above
// Basically, we are combining this Class with the 'logger' function that we created above.
Object.defineProperties(logger, {
namespace: {
value: namespace,
enumerable: true,
},
handler: {
value: handler,
},
});
// Instead of returning the class, we return the 'logger' function we created above.
return logger;
}
public extend(childNamespace: string): Logger {
return new Logger(`${this.namespace}:${childNamespace}`, this.handler.extend(childNamespace));
}
static isLogger(value: unknown): value is Logger {
return value instanceof Logger;
}
}
tests/services/config.test.ts
+120
View File
@@ -0,0 +1,120 @@
import { describe, expect, test, vi } from 'vitest';
import { Config } from '../../src/services/config.ts';
/**
* Tests that the config defaults to a 1 MiB request body limit.
*/
const testConfigDefaultsTo1MiBRequestBodyLimit = (): void => {
const config = Config.from({
database: {},
server: {},
auth: {},
});
expect(config.server.maxRequestBodyBytes).toBe(1024 * 1024);
expect(config.database.path).toBe('data.db');
expect(config.server.port).toBe(3000);
expect(config.server.host).toBe('0.0.0.0');
expect(config.server.cors.origin).toBe('*');
expect(config.server.cors.methods).toEqual([ 'GET', 'POST', 'PUT', 'DELETE', 'OPTIONS' ]);
expect(config.server.cors.allowedHeaders).toEqual([ 'Content-Type', 'cache-control', 'X-Timestamp', 'X-PublicKey', 'X-Signature' ]);
expect(config.auth.timestampWindowMs).toBe(300000);
};
/**
* Tests that the config loads the request body limit from the environment.
*/
const testConfigLoadsRequestBodyLimitFromEnvironment = (): void => {
vi.stubEnv('SERVER_MAX_REQUEST_BODY_BYTES', '2048');
expect(Config.fromEnv().server.maxRequestBodyBytes).toBe(2048);
};
/**
* Tests that the config rejects an invalid request body limit.
*/
const testConfigRejectsInvalidRequestBodyLimit = (): void => {
expect(() =>
Config.from({
database: {},
server: { maxRequestBodyBytes: '0' },
auth: {},
})).toThrow();
};
/**
* tests that the config loads the database path from the environment.
*/
const testConfigLoadsDatabasePathFromEnvironment = (): void => {
vi.stubEnv('DATABASE_PATH', 'test.db');
expect(Config.fromEnv().database.path).toBe('test.db');
};
/**
* tests that the config loads the server port from the environment.
*/
const testConfigLoadsServerPortFromEnvironment = (): void => {
vi.stubEnv('SERVER_PORT', '3000');
expect(Config.fromEnv().server.port).toBe(3000);
};
/**
* tests that the config loads the server host from the environment.
*/
const testConfigLoadsServerHostFromEnvironment = (): void => {
vi.stubEnv('SERVER_HOST', '0.0.0.0');
expect(Config.fromEnv().server.host).toBe('0.0.0.0');
};
/**
* tests that the config loads the cors configuration from the environment.
*/
const testConfigLoadsCorsConfigurationFromEnvironment = (): void => {
vi.stubEnv('CORS_ORIGIN', '*');
expect(Config.fromEnv().server.cors.origin).toBe('*');
};
/**
* tests that the config loads the cors methods from the environment.
*/
const testConfigLoadsCorsMethodsFromEnvironment = (): void => {
vi.stubEnv('CORS_METHODS', 'GET,POST,PUT,DELETE,OPTIONS');
expect(Config.fromEnv().server.cors.methods).toEqual([ 'GET', 'POST', 'PUT', 'DELETE', 'OPTIONS' ]);
};
/**
* tests that the config loads the cors allowed headers from the environment.
*/
const testConfigLoadsCorsAllowedHeadersFromEnvironment = (): void => {
vi.stubEnv('CORS_ALLOWED_HEADERS', 'Content-Type,cache-control,X-Timestamp');
expect(Config.fromEnv().server.cors.allowedHeaders).toEqual([ 'Content-Type', 'cache-control', 'X-Timestamp' ]);
};
/**
* tests that the config loads the auth configuration from the environment.
*/
const testConfigLoadsAuthConfigurationFromEnvironment = (): void => {
vi.stubEnv('AUTH_TIMESTAMP_WINDOW_MS', '1000');
expect(Config.fromEnv().auth.timestampWindowMs).toBe(1000);
};
describe('Config', () => {
test('defaults to a 1 MiB request body limit', testConfigDefaultsTo1MiBRequestBodyLimit);
test('loads the request body limit from the environment', testConfigLoadsRequestBodyLimitFromEnvironment);
test('rejects the invalid request body limit', testConfigRejectsInvalidRequestBodyLimit);
test('loads the database path from the environment', testConfigLoadsDatabasePathFromEnvironment);
test('loads the server port from the environment', testConfigLoadsServerPortFromEnvironment);
test('loads the server host from the environment', testConfigLoadsServerHostFromEnvironment);
test('loads the cors configuration from the environment', testConfigLoadsCorsConfigurationFromEnvironment);
test('loads the cors methods from the environment', testConfigLoadsCorsMethodsFromEnvironment);
test('loads the cors allowed headers from the environment', testConfigLoadsCorsAllowedHeadersFromEnvironment);
test('loads the auth configuration from the environment', testConfigLoadsAuthConfigurationFromEnvironment);
});
tests/utils/logger.test.ts
+53
View File
@@ -0,0 +1,53 @@
import { Logger } from '../../src/utils/logger.ts';
import { expect, describe, test } from 'vitest';
/**
* Tests that a logger function is created and that it is a logger.
*/
const testLoggerCreatesLoggerFunction = (): void => {
const logger = new Logger('test');
expect(logger).toBeDefined();
expect(logger.namespace).toBe('test');
expect(Logger.isLogger(logger)).toBe(true);
};
/**
* Tests that a logger function is a logger.
*/
const testLoggerFunctionIsLogger = (): void => {
const logger = new Logger('test');
expect(Logger.isLogger(logger)).toBe(true);
};
/**
* Tests that a logger extends.
*/
const testLoggerExtends = (): void => {
const logger = new Logger('test');
const extendedLogger = logger.extend('extended');
expect(extendedLogger.namespace).toBe('test:extended');
expect(Logger.isLogger(extendedLogger)).toBe(true);
};
/**
* Tests that a logger is a logger.
*/
const testLoggerIsLogger = (): void => {
const logger = new Logger('test');
expect(Logger.isLogger(logger)).toBe(true);
// Test not a logger
const notALogger = [ 'not a logger', 123, true, false, null, undefined, NaN, Infinity, -Infinity ];
for (const item of notALogger) {
expect(Logger.isLogger(item)).toBe(false);
}
};
describe('Logger', () => {
test('creates a logger function', testLoggerCreatesLoggerFunction);
test('logger function is a logger', testLoggerFunctionIsLogger);
test('logger extends', testLoggerExtends);
test('logger is logger', testLoggerIsLogger);
});
tsconfig.json
+4 -1
View File
@@ -1,15 +1,18 @@
{
"compilerOptions": {
"rootDir": "./src",
"outDir": "./dist",
"module": "es2022",
"target": "es2022",
"skipLibCheck": true,
"strict": true,
"moduleResolution": "bundler",
"resolveJsonModule": true,
"rewriteRelativeImportExtensions": true,
"allowImportingTsExtensions": true,
"noEmit": true,
"declaration": true,
"declarationMap": true
},
"exclude": ["node_modules/**/*", "dist/**/*"]
"exclude": ["node_modules/**/*", "dist/**/*", "test"]
}