Utilities to cover missing RecordId static methods

recordid-utilities.ts

import { RecordId, StringRecordId, Table } from 'surrealdb';

type RecordIdTableName<Input extends string> =
	Input extends `${infer TableName}:${string}` ? TableName : never;

/**
 * Parses a string into a RecordId, optionally validating the table name.
 *
 * @param stringRecordId The string representation of the RecordId.
 * @param table Optional table name to validate against.
 * @returns The parsed RecordId, with optional table constraint.
 * @throws Error if the string is not a valid RecordId format.
 * @throws TypeError if the table name doesn't match the expected table.
 *
 * @example
 * // Parse a RecordId string without table validation
 * const recordId = parseRecordId('user:123');
 *
 * @example
 * // Parse a RecordId string with table validation
 * const recordId = parseRecordId('post:456', 'post');
 *
 * @example
 * // Parse a StringRecordId with table validation
 * const stringRecordId = new StringRecordId('comment:789');
 * const recordId = parseRecordId(stringRecordId, 'comment');
 */
export function parseRecordId( stringRecordId: string | StringRecordId ): RecordId;
export function parseRecordId<TableName extends string>(
	stringRecordId: string | StringRecordId,
	table: TableName | Table
): RecordId<TableName>;
export function parseRecordId<TableName extends string>(
	stringRecordId: string | StringRecordId,
	table?: TableName | Table
): RecordId<TableName> | RecordId {
	const value = typeof stringRecordId === 'string' ? stringRecordId : stringRecordId.toString();
	const index = value.indexOf( ':' );
	if ( index === -1 ) {
		throw new Error( `Invalid RecordId string: ${value}` );
	}
	const recordId = new RecordId(
		value.substring( 0, index ), value.substring( index + 1 )
	);
	if ( table === undefined ) {
		return recordId;
	}
	const tableName = typeof table === 'string' ? table : table.name;
	if ( recordId.table.name !== tableName ) {
		throw new TypeError(
			`Expected RecordId with table "${tableName}", got "${recordId.table.name}"`
		);
	}
	return recordId as RecordId<TableName>;
}

/**
 * Converts a string or RecordId-like input into a RecordId instance, with optional table
 * validation.
 *
 * @param input The input to convert, which can be a string, RecordId, or StringRecordId.
 * @param table Optional table name to validate against.
 * @returns The corresponding RecordId instance.
 * @throws TypeError if the input isn't convertible to a RecordId or the table name doesn't match.
 *
 * @example
 * // Convert a string to a RecordId
 * const recordId = toRecordId('user:123');
 *
 * @example
 * // Convert a StringRecordId to a RecordId with table validation
 * const stringRecordId = new StringRecordId('post:456');
 * const recordId = toRecordId(stringRecordId, 'post');
 *
 * @example
 * // Convert a RecordId to a RecordId with table validation
 * const existingRecordId = new RecordId('comment', '789');
 * const recordId = toRecordId(existingRecordId, 'comment');
 */
export function toRecordId<const Input extends `${string}:${string}`>(
	input: Input
): RecordId<RecordIdTableName<Input>>;
export function toRecordId( input: string | RecordId | StringRecordId ): RecordId;
export function toRecordId<TableName extends string>(
	input: string | RecordId | StringRecordId,
	table: TableName | Table
): RecordId<TableName>;
export function toRecordId<TableName extends string>(
	input: string | RecordId | StringRecordId,
	table?: TableName | Table
): RecordId<TableName> | RecordId {
	if ( input instanceof RecordId ) {
		if ( table === undefined ) {
			return input;
		}
		const tableName = typeof table === 'string' ? table : table.name;
		if ( input.table.name !== tableName ) {
			throw new TypeError(
				`Expected RecordId with table "${tableName}", got "${input.table.name}"`
			);
		}
		return input as RecordId<TableName>;
	}
	if ( typeof input === 'string' || input instanceof StringRecordId ) {
		return table === undefined ? parseRecordId( input ) : parseRecordId( input, table );
	}
	throw new TypeError( `Cannot create RecordId from: ${JSON.stringify( input )}` );
}