Clean up the public API (#382)

Author: macjuul

src/data/cbor.ts

@@ -160,12 +160,22 @@ export const replacer = {
 
 Object.freeze(replacer);
 
+/**
+ * Recursively encode any supported SurrealQL value into a binary CBOR representation.
+ * @param data - The input value
+ * @returns CBOR binary representation
+ */
 export function encodeCbor<T>(data: T): ArrayBuffer {
 	return encode(data, {
 		replacer: replacer.encode,
 	});
 }
 
+/**
+ * Decode a CBOR encoded SurrealQL value into object representation.
+ * @param data - The encoded SurrealQL value
+ * @returns The parsed SurrealQL value
+ */
 // biome-ignore lint/suspicious/noExplicitAny: Don't know what it will return
 export function decodeCbor(data: ArrayBufferLike): any {
 	return decode(data, {

src/data/index.ts

@@ -2,7 +2,6 @@ export {
 	RecordId,
 	StringRecordId,
 	type RecordIdValue,
-	escape_ident,
 } from "./types/recordid.ts";
 export {
 	Range,

src/data/types/decimal.ts

@@ -1,5 +1,8 @@
 import { Value } from "../value";
 
+/**
+ * A SurrealQL decimal value.
+ */
 export class Decimal extends Value {
 	readonly decimal: string;
 

src/data/types/duration.ts

@@ -32,6 +32,9 @@ const durationPartRegex = new RegExp(
 	`^(\\d+)(${Array.from(units.keys()).join("|")})`,
 );
 
+/**
+ * A SurrealQL duration value.
+ */
 export class Duration extends Value {
 	readonly _milliseconds: number;
 

src/data/types/future.ts

@@ -1,5 +1,8 @@
 import { Value } from "../value";
 
+/**
+ * An uncomputed SurrealQL future value.
+ */
 export class Future extends Value {
 	constructor(readonly inner: string) {
 		super();

src/data/types/geometry.ts

@@ -1,6 +1,9 @@
 import { Value } from "../value.ts";
 import { Decimal } from "./decimal.ts";
 
+/**
+ * A SurrealQL geometry value.
+ */
 export abstract class Geometry extends Value {
 	abstract toJSON(): GeoJson;
 	abstract is(geometry: Geometry): boolean;
@@ -21,6 +24,9 @@ function f(num: number | Decimal) {
 	return num;
 }
 
+/**
+ * A SurrealQL point geometry value.
+ */
 export class GeometryPoint extends Geometry {
 	readonly point: [number, number];
 
@@ -56,6 +62,9 @@ export class GeometryPoint extends Geometry {
 	}
 }
 
+/**
+ * A SurrealQL line geometry value.
+ */
 export class GeometryLine extends Geometry {
 	readonly line: [GeometryPoint, GeometryPoint, ...GeometryPoint[]];
 
@@ -108,6 +117,9 @@ export class GeometryLine extends Geometry {
 	}
 }
 
+/**
+ * A SurrealQL polygon geometry value.
+ */
 export class GeometryPolygon extends Geometry {
 	readonly polygon: [GeometryLine, ...GeometryLine[]];
 
@@ -153,6 +165,9 @@ export class GeometryPolygon extends Geometry {
 	}
 }
 
+/**
+ * A SurrealQL multi-point geometry value.
+ */
 export class GeometryMultiPoint extends Geometry {
 	readonly points: [GeometryPoint, ...GeometryPoint[]];
 
@@ -193,6 +208,9 @@ export class GeometryMultiPoint extends Geometry {
 	}
 }
 
+/**
+ * A SurrealQL multi-line geometry value.
+ */
 export class GeometryMultiLine extends Geometry {
 	readonly lines: [GeometryLine, ...GeometryLine[]];
 
@@ -231,6 +249,9 @@ export class GeometryMultiLine extends Geometry {
 	}
 }
 
+/**
+ * A SurrealQL multi-polygon geometry value.
+ */
 export class GeometryMultiPolygon extends Geometry {
 	readonly polygons: [GeometryPolygon, ...GeometryPolygon[]];
 
@@ -275,6 +296,9 @@ export class GeometryMultiPolygon extends Geometry {
 	}
 }
 
+/**
+ * A SurrealQL geometry collection value.
+ */
 export class GeometryCollection extends Geometry {
 	readonly collection: [Geometry, ...Geometry[]];
 

src/data/types/range.ts

@@ -1,16 +1,15 @@
 import { Tagged } from "../../cbor";
 import { SurrealDbError } from "../../errors";
 import { equals } from "../../util/equals";
+import { escapeIdent } from "../../util/escape";
 import { toSurrealqlString } from "../../util/to-surrealql-string";
 import { TAG_BOUND_EXCLUDED, TAG_BOUND_INCLUDED } from "../cbor";
 import { Value } from "../value";
-import {
-	type RecordIdValue,
-	escape_id_part,
-	escape_ident,
-	isValidIdPart,
-} from "./recordid";
+import { type RecordIdValue, escapeIdPart, isValidIdPart } from "./recordid";
 
+/**
+ * A SurrealQL range value.
+ */
 export class Range<Beg, End> extends Value {
 	constructor(
 		readonly beg: Bound<Beg>,
@@ -34,8 +33,8 @@ export class Range<Beg, End> extends Value {
 	}
 
 	toString(): string {
-		const beg = escape_range_bound(this.beg);
-		const end = escape_range_bound(this.end);
+		const beg = escapeRangeBound(this.beg);
+		const end = escapeRangeBound(this.end);
 		return `${beg}${getRangeJoin(this.beg, this.end)}${end}`;
 	}
 }
@@ -49,6 +48,9 @@ export class BoundExcluded<T> {
 	constructor(readonly value: T) {}
 }
 
+/**
+ * A SurrealQL record ID range value.
+ */
 export class RecordIdRange<Tb extends string = string> extends Value {
 	constructor(
 		public readonly tb: Tb,
@@ -78,9 +80,9 @@ export class RecordIdRange<Tb extends string = string> extends Value {
 	}
 
 	toString(): string {
-		const tb = escape_ident(this.tb);
-		const beg = escape_id_bound(this.beg);
-		const end = escape_id_bound(this.end);
+		const tb = escapeIdent(this.tb);
+		const beg = escapeIdBound(this.beg);
+		const end = escapeIdBound(this.end);
 		return `${tb}:${beg}${getRangeJoin(this.beg, this.end)}${end}`;
 	}
 }
@@ -99,13 +101,13 @@ function isValidIdBound(bound: Bound<unknown>): bound is Bound<RecordIdValue> {
 		: true;
 }
 
-function escape_id_bound(bound: Bound<RecordIdValue>): string {
+function escapeIdBound(bound: Bound<RecordIdValue>): string {
 	return bound instanceof BoundIncluded || bound instanceof BoundExcluded
-		? escape_id_part(bound.value)
+		? escapeIdPart(bound.value)
 		: "";
 }
 
-function escape_range_bound(bound: Bound<unknown>): string {
+function escapeRangeBound(bound: Bound<unknown>): string {
 	if (bound === undefined) return "";
 	const value = bound.value;
 

src/data/types/recordid.ts

@@ -1,10 +1,10 @@
 import { SurrealDbError } from "../../errors";
 import { equals } from "../../util/equals";
+import { escapeIdent, escapeNumber } from "../../util/escape";
 import { toSurrealqlString } from "../../util/to-surrealql-string";
 import { Value } from "../value";
 import { Uuid } from "./uuid";
 
-const MAX_i64 = 9223372036854775807n;
 export type RecordIdValue =
 	| string
 	| number
@@ -13,6 +13,9 @@ export type RecordIdValue =
 	| unknown[]
 	| Record<string, unknown>;
 
+/**
+ * A SurrealQL record ID value.
+ */
 export class RecordId<Tb extends string = string> extends Value {
 	public readonly tb: Tb;
 	public readonly id: RecordIdValue;
@@ -38,12 +41,15 @@ export class RecordId<Tb extends string = string> extends Value {
 	}
 
 	toString(): string {
-		const tb = escape_ident(this.tb);
-		const id = escape_id_part(this.id);
+		const tb = escapeIdent(this.tb);
+		const id = escapeIdPart(this.id);
 		return `${tb}:${id}`;
 	}
 }
 
+/**
+ * A SurrealQL string-represented record ID value.
+ */
 export class StringRecordId extends Value {
 	public readonly rid: string;
 
@@ -77,41 +83,6 @@ export class StringRecordId extends Value {
 	}
 }
 
-export function escape_number(num: number | bigint): string {
-	return num <= MAX_i64 ? num.toString() : `⟨${num}⟩`;
-}
-
-export function escape_ident(str: string): string {
-	// String which looks like a number should always be escaped, to prevent it from being parsed as a number
-	if (isOnlyNumbers(str)) {
-		return `⟨${str}⟩`;
-	}
-
-	let code: number;
-	let i: number;
-	let len: number;
-
-	for (i = 0, len = str.length; i < len; i++) {
-		code = str.charCodeAt(i);
-		if (
-			!(code > 47 && code < 58) && // numeric (0-9)
-			!(code > 64 && code < 91) && // upper alpha (A-Z)
-			!(code > 96 && code < 123) && // lower alpha (a-z)
-			!(code === 95) // underscore (_)
-		) {
-			return `⟨${str.replaceAll("⟩", "\\⟩")}⟩`;
-		}
-	}
-
-	return str;
-}
-
-export function isOnlyNumbers(str: string): boolean {
-	const stripped = str.replace("_", "");
-	const parsed = Number.parseInt(stripped);
-	return !Number.isNaN(parsed) && parsed.toString() === stripped;
-}
-
 export function isValidIdPart(v: unknown): v is RecordIdValue {
 	if (v instanceof Uuid) return true;
 
@@ -127,12 +98,12 @@ export function isValidIdPart(v: unknown): v is RecordIdValue {
 	}
 }
 
-export function escape_id_part(id: RecordIdValue): string {
+export function escapeIdPart(id: RecordIdValue): string {
 	return id instanceof Uuid
 		? `u"${id}"`
 		: typeof id === "string"
-			? escape_ident(id)
+			? escapeIdent(id)
 			: typeof id === "bigint" || typeof id === "number"
-				? escape_number(id)
+				? escapeNumber(id)
 				: toSurrealqlString(id);
 }

src/data/types/table.ts

@@ -1,6 +1,9 @@
 import { SurrealDbError } from "../../errors";
 import { Value } from "../value";
 
+/**
+ * A SurrealQL table value.
+ */
 export class Table<Tb extends string = string> extends Value {
 	public readonly tb: Tb;
 

src/data/types/uuid.ts

@@ -1,6 +1,9 @@
 import { UUID, uuidv4obj, uuidv7obj } from "uuidv7";
 import { Value } from "../value";
 
+/**
+ * A SurrealQL UUID value.
+ */
 export class Uuid extends Value {
 	private readonly inner: UUID;
 

src/data/value.ts

@@ -1,3 +1,6 @@
+/**
+ * A complex SurrealQL value type
+ */
 export abstract class Value {
 	/**
 	 * Compare equality with another value.

src/index.ts

@@ -13,6 +13,7 @@ export * from "./util/version-check.ts";
 export * from "./util/get-incremental-id.ts";
 export * from "./util/string-prefixes.ts";
 export * from "./util/to-surrealql-string.ts";
+export * from "./util/escape.ts";
 export {
 	ConnectionStatus,
 	AbstractEngine,