@zyno-io/dk-server-foundation 26.216.430

package/src/testing/index.ts

@@ -0,0 +1,355 @@
+import { App, RootModuleDefinition } from '@deepkit/app';
+import { ClassType } from '@deepkit/core';
+import { ApplicationServer, TestingFacade as BaseTestingFacade } from '@deepkit/framework';
+import { MySQLDatabaseAdapter } from '@deepkit/mysql';
+import { DatabaseRegistry } from '@deepkit/orm';
+import { PostgresDatabaseAdapter } from '@deepkit/postgres';
+
+import { BaseAppConfig, createApp, CreateAppOptions } from '../app';
+import { globalState } from '../app/state';
+import { runMigrations } from '../database';
+import { sleepMs } from '../helpers';
+import { defineEntityFixtures, loadEntityFixtures, prepareEntityFixtures } from './fixtures';
+import { installStandardHooks, makeMockRequest, resetSrcModuleCache } from './requests';
+import { SqlTestingHelper } from './sql';
+
+process.env.TEST_RUN_TS ??= String(Math.floor(Date.now() / 1000));
+
+let nextPoolId = 1;
+
+export type TestDbAdapter = 'mysql' | 'postgres';
+
+function getTestDbAdapter(): TestDbAdapter {
+    if (process.env.DB_ADAPTER === 'postgres' || process.env.DB_ADAPTER === 'mysql') {
+        return process.env.DB_ADAPTER;
+    }
+    if (process.env.PG_HOST) return 'postgres';
+    return 'mysql';
+}
+
+export interface ITestingFacadeOptions {
+    enableDatabase?: boolean;
+    enableMigrations?: boolean;
+    autoSeedData?: boolean;
+    databasePrefix?: string;
+    dbAdapter?: TestDbAdapter;
+    onBeforeStart?: (facade: TestingFacade) => Promise<void>;
+    onStart?: (facade: TestingFacade) => Promise<void>;
+    onBeforeStop?: (facade: TestingFacade) => Promise<void>;
+    onStop?: (facade: TestingFacade) => Promise<void>;
+    seedData?: (facade: TestingFacade) => Promise<void>;
+    defaultTestHeaders?: Record<string, string>;
+}
+
+export class TestingFacade<A extends RootModuleDefinition = RootModuleDefinition> extends BaseTestingFacade<App<A>> {
+    public sql = new SqlTestingHelper();
+    public startTs = 0;
+    public databaseName?: string;
+    public dbAdapter: TestDbAdapter;
+    private stopped = false;
+    private httpServer?: import('net').Server;
+
+    constructor(
+        app: App<A>,
+        public readonly options: ITestingFacadeOptions = {}
+    ) {
+        super(app);
+        this.dbAdapter = options.dbAdapter ?? getTestDbAdapter();
+    }
+
+    public async start() {
+        if (this.options?.enableDatabase) {
+            await this.createDatabase();
+        }
+
+        await this.options?.onBeforeStart?.(this);
+
+        if (this.databaseName) {
+            if (this.dbAdapter === 'postgres') {
+                process.env.PG_DATABASE = this.databaseName;
+            } else {
+                process.env.MYSQL_DATABASE = this.databaseName;
+            }
+        }
+
+        // Ensure globalState points to this app before starting the server.
+        // When multiple test facades are created (e.g. forEachAdapter), the last
+        // createApp() call wins. Without this, the DB constructor's getAppConfig()
+        // would resolve against the wrong app, eagerly loading its config from
+        // stale env vars.
+        globalState.currentApp = this.app;
+
+        await this.startServer();
+
+        try {
+            const appServer = this.app.get(ApplicationServer);
+            const worker = appServer.getWorker();
+            this.httpServer = worker['server']!;
+            this.httpServer.on('listening', () => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                process.stdout.write(`HTTP listening at http://127.0.0.1:${(this.httpServer!.address() as any).port}.\n`);
+            });
+
+            this.startTs = Date.now();
+
+            await this.options?.onStart?.(this);
+
+            if (this.options?.enableDatabase) {
+                if (this.options?.enableMigrations !== false) {
+                    await this.runMigrations();
+                    await this.truncateTables();
+                }
+                if (this.options?.autoSeedData) {
+                    await this.options?.seedData?.(this);
+                }
+            }
+        } catch (err) {
+            await this.stop();
+            throw err;
+        }
+    }
+
+    public async stop() {
+        if (this.stopped) return;
+        this.stopped = true;
+
+        await this.options?.onBeforeStop?.(this);
+
+        // if the server is running for too short of a time, the database handshake
+        // gets interrupted and the client hangs due to poor behaivor. thus,
+        // we ensure we wait a minimum duration prior to telling the server to shut down.
+        const durationMs = Date.now() - this.startTs;
+        const waitMs = Math.max(0, 500 - durationMs);
+        if (waitMs) await sleepMs(waitMs);
+        await this.stopServer(true);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (this.httpServer as any)?.closeAllConnections?.();
+
+        if (this.options?.enableDatabase) {
+            try {
+                this.app.get(DatabaseRegistry).onShutDown();
+            } catch {
+                // pool may already be closed if start() failed partway through
+            }
+        }
+
+        await this.options?.onStop?.(this);
+    }
+
+    /**
+     * ADDITIONS
+     */
+
+    public async createDatabase() {
+        const ts = process.env.TEST_RUN_TS ?? Math.floor(Date.now() / 1000);
+        const poolId = nextPoolId++;
+        this.databaseName = `${this.options?.databasePrefix ?? 'test'}_${ts}_${process.pid}_${poolId}`;
+
+        if (this.dbAdapter === 'postgres') {
+            const pgAdapter = new PostgresDatabaseAdapter({
+                host: process.env.PG_HOST,
+                port: process.env.PG_PORT ? parseInt(process.env.PG_PORT) : 5432,
+                user: process.env.PG_USER,
+                password: process.env.PG_PASSWORD_SECRET,
+                database: 'postgres'
+            });
+            const pgConn = await pgAdapter.connectionPool.getConnection();
+            await pgConn.run(`CREATE DATABASE "${this.databaseName}"`);
+            await pgConn.release();
+            await pgAdapter.disconnect();
+        } else {
+            const dbAdapter = new MySQLDatabaseAdapter({
+                host: process.env.MYSQL_HOST,
+                port: process.env.MYSQL_PORT ? parseInt(process.env.MYSQL_PORT) : 3306,
+                user: process.env.MYSQL_USER,
+                password: process.env.MYSQL_PASSWORD_SECRET,
+                database: 'mysql',
+                allowPublicKeyRetrieval: true,
+                trace: true
+            });
+            const dbConn = await dbAdapter.connectionPool.getConnection();
+            await dbConn.run(`CREATE DATABASE IF NOT EXISTS ${this.databaseName}`);
+            await dbConn.release();
+            await dbAdapter.disconnect();
+        }
+    }
+
+    public async destroyDatabase() {
+        if (!this.databaseName || process.env.TEST_KEEP_DB) return;
+
+        if (this.dbAdapter === 'postgres') {
+            const pgAdapter = new PostgresDatabaseAdapter({
+                host: process.env.PG_HOST,
+                port: process.env.PG_PORT ? parseInt(process.env.PG_PORT) : 5432,
+                user: process.env.PG_USER,
+                password: process.env.PG_PASSWORD_SECRET,
+                database: 'postgres'
+            });
+            const pgConn = await pgAdapter.connectionPool.getConnection();
+            await pgConn.run(`DROP DATABASE IF EXISTS "${this.databaseName}"`);
+            await pgConn.release();
+            await pgAdapter.disconnect();
+        } else {
+            const dbAdapter = new MySQLDatabaseAdapter({
+                host: process.env.MYSQL_HOST,
+                port: process.env.MYSQL_PORT ? parseInt(process.env.MYSQL_PORT) : 3306,
+                user: process.env.MYSQL_USER,
+                password: process.env.MYSQL_PASSWORD_SECRET,
+                database: 'mysql',
+                allowPublicKeyRetrieval: true,
+                trace: true
+            });
+            const dbConn = await dbAdapter.connectionPool.getConnection();
+            await dbConn.run(`DROP DATABASE IF EXISTS ${this.databaseName}`);
+            await dbConn.release();
+            await dbAdapter.disconnect();
+        }
+    }
+
+    public async truncateTables() {
+        if (this.dbAdapter === 'postgres') {
+            const pgAdapter = new PostgresDatabaseAdapter({
+                host: process.env.PG_HOST,
+                port: process.env.PG_PORT ? parseInt(process.env.PG_PORT) : 5432,
+                user: process.env.PG_USER,
+                password: process.env.PG_PASSWORD_SECRET,
+                database: this.databaseName!
+            });
+            const pgConn = await pgAdapter.connectionPool.getConnection();
+            try {
+                const result = await pgConn.execAndReturnAll(`SELECT tablename FROM pg_tables WHERE schemaname = 'public'`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const tables = result.map((row: any) => row.tablename);
+                for (const table of tables) {
+                    if (table === '_migrations') continue;
+                    await pgConn.run(`TRUNCATE TABLE "${table}" CASCADE`);
+                }
+            } finally {
+                await pgConn.release();
+                await pgAdapter.disconnect();
+            }
+        } else {
+            const dbAdapter = new MySQLDatabaseAdapter({
+                host: process.env.MYSQL_HOST,
+                port: process.env.MYSQL_PORT ? parseInt(process.env.MYSQL_PORT) : 3306,
+                user: process.env.MYSQL_USER,
+                password: process.env.MYSQL_PASSWORD_SECRET,
+                database: this.databaseName!,
+                allowPublicKeyRetrieval: true,
+                trace: true
+            });
+            const dbConn = await dbAdapter.connectionPool.getConnection();
+            try {
+                const result = await dbConn.execAndReturnAll('SHOW TABLES');
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const tables = result.map((row: any) => Object.values(row)[0]);
+                for (const table of tables) {
+                    if (table === '_migrations') continue;
+                    await dbConn.run(`TRUNCATE TABLE ${table}`);
+                }
+            } finally {
+                await dbConn.release();
+                await dbAdapter.disconnect();
+            }
+        }
+    }
+
+    public async runMigrations() {
+        await runMigrations();
+    }
+
+    public async resetToSeed() {
+        if (!this.options?.enableDatabase) return;
+        await this.truncateTables();
+        await this.options?.seedData?.(this);
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type TestingAppOptions<C> = Omit<CreateAppOptions<any>, 'config'> & { config?: ClassType<C> };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function createTestingFacade<O extends TestingAppOptions<any>>(appOptions: O, options?: ITestingFacadeOptions) {
+    const adapter = getTestDbAdapter();
+    if (!options?.enableDatabase) {
+        if (adapter === 'mysql') {
+            process.env.MYSQL_MIN_IDLE_CONNECTIONS = '0';
+        }
+    }
+    const app = createApp({
+        config: BaseAppConfig,
+        ...appOptions,
+        frameworkConfig: {
+            ...appOptions.frameworkConfig,
+            port: 0,
+            compression: 0
+        }
+    });
+    return new TestingFacade(app, options);
+}
+
+type MySQLConfig = Pick<BaseAppConfig, 'MYSQL_HOST' | 'MYSQL_PORT' | 'MYSQL_USER' | 'MYSQL_PASSWORD_SECRET'>;
+type PGConfig = Pick<BaseAppConfig, 'PG_HOST' | 'PG_PORT' | 'PG_USER' | 'PG_PASSWORD_SECRET'>;
+
+function setDefaultDatabaseConfig(config: MySQLConfig | PGConfig) {
+    Object.assign(process.env, { ...config, ...process.env });
+    if ('PG_HOST' in config) {
+        process.env.PG_DATABASE ??= '_fake_database_';
+    } else {
+        process.env.MYSQL_DATABASE ??= '_fake_database_';
+    }
+}
+
+async function cleanupTestDatabases(prefix?: string, except?: string) {
+    const dbNameRe = new RegExp(`^${prefix ?? 'test'}_\\d+_\\d+_\\d+$`);
+    const adapter = getTestDbAdapter();
+
+    if (adapter === 'postgres') {
+        const pgAdapter = new PostgresDatabaseAdapter({
+            host: process.env.PG_HOST,
+            port: process.env.PG_PORT ? parseInt(process.env.PG_PORT) : 5432,
+            user: process.env.PG_USER,
+            password: process.env.PG_PASSWORD_SECRET,
+            database: 'postgres'
+        });
+        const pgConn = await pgAdapter.connectionPool.getConnection();
+        const result = await pgConn.execAndReturnAll(`SELECT datname AS "Database" FROM pg_database WHERE datistemplate = false`);
+        const dbs = result.map((r: { Database: string }) => r.Database).filter((db: string) => dbNameRe.test(db));
+        for (const db of dbs) {
+            if (db === except) continue;
+            await pgConn.run(`DROP DATABASE "${db}"`);
+        }
+        await pgConn.release();
+        await pgAdapter.disconnect();
+    } else {
+        const dbAdapter = new MySQLDatabaseAdapter({
+            host: process.env.MYSQL_HOST,
+            port: process.env.MYSQL_PORT ? parseInt(process.env.MYSQL_PORT) : 3306,
+            user: process.env.MYSQL_USER,
+            password: process.env.MYSQL_PASSWORD_SECRET,
+            database: 'mysql',
+            allowPublicKeyRetrieval: true,
+            trace: true
+        });
+        const dbConn = await dbAdapter.connectionPool.getConnection();
+        const result = await dbConn.execAndReturnAll(`SHOW DATABASES`);
+        const dbs = result.map((r: { Database: string }) => r.Database).filter((db: string) => dbNameRe.test(db));
+        for (const db of dbs) {
+            if (db === except) continue;
+            await dbConn.run(`DROP DATABASE ${db}`);
+        }
+        await dbConn.release();
+        await dbAdapter.disconnect();
+    }
+}
+
+export const TestingHelpers = {
+    setDefaultDatabaseConfig,
+    createTestingFacade,
+    cleanupTestDatabases,
+    defineEntityFixtures,
+    prepareEntityFixtures,
+    loadEntityFixtures,
+    makeMockRequest,
+    installStandardHooks,
+    resetSrcModuleCache
+};

package/src/testing/requests.ts

@@ -0,0 +1,68 @@
+import { mock, before, after, beforeEach, afterEach } from 'node:test';
+import { HttpRequest, MemoryHttpResponse } from '@deepkit/http';
+import { MySQLConnectionPool, MySQLDatabaseAdapter } from '@deepkit/mysql';
+import { PostgresConnectionPool, PostgresDatabaseAdapter } from '@deepkit/postgres';
+import { TestingFacade } from '.';
+
+function installDbRejectionHooks() {
+    mock.method(MySQLConnectionPool.prototype, 'getConnection', () => {
+        throw new Error('Database is not enabled in testing mode');
+    });
+    mock.method(MySQLDatabaseAdapter.prototype, 'disconnect', () => {});
+
+    mock.method(PostgresConnectionPool.prototype, 'getConnection', () => {
+        throw new Error('Database is not enabled in testing mode');
+    });
+    mock.method(PostgresDatabaseAdapter.prototype, 'disconnect', () => {});
+}
+
+export function installStandardHooks(tf: TestingFacade) {
+    before(() => tf.start());
+    after(() => tf.stop());
+
+    if (!tf.options?.enableDatabase) {
+        beforeEach(() => installDbRejectionHooks());
+        afterEach(() => tf.sql.clearMocks());
+    }
+
+    beforeEach(() => tf.resetToSeed());
+    afterEach(() => {
+        mock.timers.reset();
+        mock.restoreAll();
+    });
+}
+
+export function resetSrcModuleCache() {
+    for (const key of Object.keys(require.cache)) {
+        if (key.includes('/dist/src/') || key.includes('/src/')) {
+            delete require.cache[key];
+        }
+    }
+}
+
+type MockMethod = 'GET' | 'PUT' | 'POST' | 'DELETE';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type MockBody = Record<string, any>;
+export async function makeMockRequest(tf: TestingFacade, method: MockMethod, url: string, body: MockBody): Promise<MemoryHttpResponse>;
+export async function makeMockRequest(
+    tf: TestingFacade,
+    method: MockMethod,
+    url: string,
+    headers: Record<string, string>,
+    body: MockBody
+): Promise<MemoryHttpResponse>;
+export async function makeMockRequest(
+    tf: TestingFacade,
+    method: MockMethod,
+    url: string,
+    headersOrBody: Record<string, string> | MockBody,
+    body?: MockBody
+): Promise<MemoryHttpResponse> {
+    const headers = body ? headersOrBody : tf.options?.defaultTestHeaders;
+    return tf.request(
+        HttpRequest[method](url)
+            .headers({ 'content-type': 'application/json', ...headers })
+            .body(JSON.stringify(body ?? headersOrBody))
+    );
+}

package/src/testing/sql.ts

@@ -0,0 +1,50 @@
+import { mock } from 'node:test';
+import { ClassType } from '@deepkit/core';
+import { MySQLDatabaseAdapter } from '@deepkit/mysql';
+import { DatabasePersistence, MemoryDatabaseAdapter, MemoryQueryFactory, OrmEntity } from '@deepkit/orm';
+import { PostgresDatabaseAdapter } from '@deepkit/postgres';
+import { ReflectionClass } from '@deepkit/type';
+import { EntityFields } from '../database';
+
+export class SqlTestingHelper {
+    private mdbAdapter?: MemoryDatabaseAdapter;
+    private mdbPersistence?: DatabasePersistence;
+
+    mockEntity<T extends OrmEntity>(entityCls: ClassType<T>, data: Partial<EntityFields<T>>[] | Partial<EntityFields<T>>) {
+        const entityRefCls = ReflectionClass.from(entityCls);
+        this.mdbAdapter ??= new MemoryDatabaseAdapter();
+        this.mdbPersistence ??= this.mdbAdapter.createPersistence();
+        this.mdbPersistence.insert(entityRefCls, Array.isArray(data) ? data : [data]);
+        this.installMocks();
+    }
+
+    clearMocks() {
+        this.mdbAdapter?.['store'].clear();
+    }
+
+    installMocks() {
+        // Mock MySQL adapter
+        const mysqlQfDescriptor = Object.getOwnPropertyDescriptor(MySQLDatabaseAdapter.prototype, 'queryFactory');
+        if (!(mysqlQfDescriptor && 'value' in mysqlQfDescriptor && mysqlQfDescriptor.value?.mock)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mock.method(MySQLDatabaseAdapter.prototype, 'queryFactory', (session: any) => this.mdbAdapter!.queryFactory(session) as any);
+        }
+
+        // Mock Postgres adapter
+        const pgQfDescriptor = Object.getOwnPropertyDescriptor(PostgresDatabaseAdapter.prototype, 'queryFactory');
+        if (!(pgQfDescriptor && 'value' in pgQfDescriptor && pgQfDescriptor.value?.mock)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mock.method(PostgresDatabaseAdapter.prototype, 'queryFactory', (session: any) => this.mdbAdapter!.queryFactory(session) as any);
+        }
+
+        const mdbAdapter = this.mdbAdapter;
+        const originalCreateQuery = MemoryQueryFactory.prototype.createQuery;
+        mock.method(MemoryQueryFactory.prototype, 'createQuery', function (this: MemoryQueryFactory, entity: ClassType) {
+            const entityRefCls = ReflectionClass.from(entity);
+            if (!mdbAdapter?.['store'].has(entityRefCls)) {
+                throw new Error(`No mock data found for entity: ${entityRefCls.getClassName()}`);
+            }
+            return originalCreateQuery.call(this, entity);
+        });
+    }
+}

package/src/types/index.ts

@@ -0,0 +1,64 @@
+import { TypeAnnotation } from '@deepkit/core';
+import { DatabaseField, MinLength, Pattern, serializer, typeAnnotation, Validate, ValidatorError } from '@deepkit/type';
+
+export * from './phone';
+
+export type ConcretePrimitive = string | number | boolean;
+export type DefinedPrimitive = ConcretePrimitive | null;
+export type Primitive = DefinedPrimitive | undefined;
+export type StrictBool = true | false;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type KVObject<T = any> = Record<string, T>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type NestedKVObject<T = any> = KVObject<T | T[] | KVObject<T>>;
+export type Serializable<T = ConcretePrimitive> = T | T[] | NestedKVObject<T> | NestedKVObject<T>[];
+
+export type RequireFields<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type ObjectKeysMatching<O extends {}, V> = { [K in keyof O]: O[K] extends V ? K : V extends O[K] ? K : never }[keyof O];
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ArrowFunction = (...args: any) => any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ArrowFunctionNoArgs = () => any;
+export type VoidFunction = () => void;
+
+type IfAny<T, Y, N> = 0 extends 1 & T ? Y : N;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type DefinitelyFunction<T> = IfAny<T, never, T extends (...args: any[]) => any ? T : never>;
+export type MethodsOf<T> = {
+    [K in keyof T as DefinitelyFunction<T[K]> extends never ? never : K]: T[K];
+};
+export type MethodKeys<T> = keyof MethodsOf<T>;
+
+const _dateStringPattern = /^\d{4}-\d{2}-\d{2}$/;
+export type DateString = string & Pattern<typeof _dateStringPattern> & DatabaseField<{ type: 'DATE' }> & TypeAnnotation<'dksf:type', 'date'>;
+
+export type OnUpdate<T extends string> = TypeAnnotation<'dksf:onUpdate', T>;
+
+export type ValidDate = Date & Validate<typeof _validateDate>;
+function _validateDate(value: unknown) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (!(value instanceof Date) || isNaN(value as any)) {
+        return new ValidatorError('invalidDate', 'The date invalid.');
+    }
+}
+
+// trimmed string
+export type TrimmedString = string & TypeAnnotation<'dksf:trim'>;
+export type NonEmptyTrimmedString = TrimmedString & MinLength<1>;
+serializer.deserializeRegistry.addDecorator(
+    t => typeAnnotation.getType(t, 'dksf:trim') !== undefined,
+    (_type, state) => {
+        state.addSetter(`${state.accessor}.trim()`);
+    }
+);
+
+// email
+// DK's doesn't do a full FQDN w/TLD check
+// https://github.com/deepkit/deepkit-framework/pull/558
+export const EMAIL_REGEX = /^[a-z0-9_+.-]+@[a-z0-9-.]+\.[a-z]+$/i;
+export type EmailAddress = string & Pattern<typeof EMAIL_REGEX>;

package/src/types/phone.ts

@@ -0,0 +1,64 @@
+import { TypeAnnotation } from '@deepkit/core';
+import { ReflectionKind, serializer, typeAnnotation, Validate, ValidatorError } from '@deepkit/type';
+import { PhoneNumberFormat, PhoneNumberUtil } from 'google-libphonenumber';
+
+import { tryOrErrorSync } from '../helpers';
+
+const PhoneFormatter = PhoneNumberUtil.getInstance();
+const InvalidPhoneSymbol = '¡InvalidPhone¡'; //Symbol('InvalidPhone');
+
+export function cleanPhone(value: string, country: string = 'US'): string | null {
+    const cleaned = cleanPhoneInternal(value, country);
+    return cleaned === InvalidPhoneSymbol ? null : cleaned;
+}
+
+function cleanPhoneInternal(value: string, country: string = 'US', stripUSPrefix = false): string {
+    if (typeof value !== 'string') return InvalidPhoneSymbol;
+    const number = tryOrErrorSync(() => PhoneFormatter.parseAndKeepRawInput(value, country));
+    if (number instanceof Error) return InvalidPhoneSymbol;
+    if (!PhoneFormatter.isValidNumber(number)) return InvalidPhoneSymbol;
+    const result = PhoneFormatter.format(number, PhoneNumberFormat.E164);
+    return stripUSPrefix ? result.replace(/^\+1/, '') : result;
+}
+
+export function formatPhoneFriendly(value: string, country?: string): string | null {
+    const number = tryOrErrorSync(() => PhoneFormatter.parse(value, country));
+    if (number instanceof Error) return null;
+    if (!PhoneFormatter.isValidNumber(number)) return null;
+    return PhoneFormatter.format(number, PhoneNumberFormat.NATIONAL);
+}
+
+function _validatePhone(value: unknown) {
+    if (value === InvalidPhoneSymbol) {
+        return new ValidatorError('invalidPhone', 'The phone number is invalid.');
+    }
+}
+
+serializer.deserializeRegistry.addDecorator(
+    t => {
+        const typeType = typeAnnotation.getType(t, 'dksf:type');
+        return typeType?.kind === ReflectionKind.literal && typeType.literal === 'phone';
+    },
+    (_type, state) => {
+        state.setContext({ cleanPhoneInternal });
+        state.addCodeForSetter(`
+            ${state.setter} = cleanPhoneInternal(${state.accessor});
+        `);
+    }
+);
+
+serializer.deserializeRegistry.addDecorator(
+    t => {
+        const typeType = typeAnnotation.getType(t, 'dksf:type');
+        return typeType?.kind === ReflectionKind.literal && typeType.literal === 'phoneNanp';
+    },
+    (_type, state) => {
+        state.setContext({ cleanPhoneInternal });
+        state.addCodeForSetter(`
+            ${state.setter} = cleanPhoneInternal(${state.accessor}, 'US', true);
+        `);
+    }
+);
+
+export type PhoneNumber = string & Validate<typeof _validatePhone> & TypeAnnotation<'dksf:type', 'phone'>;
+export type PhoneNumberNANP = string & Validate<typeof _validatePhone> & TypeAnnotation<'dksf:type', 'phoneNanp'>;

package/types.d.ts

@@ -0,0 +1,20 @@
+declare module 'opentelemetry-node-metrics' {
+    // unclear why I can't import @opentelemetry/api without this file blowing up
+    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    export default function (provider: any): void;
+}
+
+declare module 'send' {
+    import { IncomingMessage } from 'http';
+    import { Stream } from 'stream';
+
+    interface SendStream extends Stream {
+        on(event: 'error', fn: (err: { status: number }) => void): this;
+        on(event: 'end', fn: () => void): this;
+        pipe<T extends NodeJS.WritableStream>(destination: T): T;
+    }
+
+    function send(req: IncomingMessage, path: string, options?: { root?: string }): SendStream;
+    export = send;
+}