Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clean up the public API #382

Merged
merged 2 commits into from
Nov 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions src/data/cbor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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, {
Expand Down
1 change: 0 additions & 1 deletion src/data/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ export {
RecordId,
StringRecordId,
type RecordIdValue,
escape_ident,
} from "./types/recordid.ts";
export {
Range,
Expand Down
3 changes: 3 additions & 0 deletions src/data/types/decimal.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { Value } from "../value";

/**
* A SurrealQL decimal value.
*/
export class Decimal extends Value {
readonly decimal: string;

Expand Down
3 changes: 3 additions & 0 deletions src/data/types/duration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
3 changes: 3 additions & 0 deletions src/data/types/future.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { Value } from "../value";

/**
* An uncomputed SurrealQL future value.
*/
export class Future extends Value {
constructor(readonly inner: string) {
super();
Expand Down
24 changes: 24 additions & 0 deletions src/data/types/geometry.ts
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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];

Expand Down Expand Up @@ -56,6 +62,9 @@ export class GeometryPoint extends Geometry {
}
}

/**
* A SurrealQL line geometry value.
*/
export class GeometryLine extends Geometry {
readonly line: [GeometryPoint, GeometryPoint, ...GeometryPoint[]];

Expand Down Expand Up @@ -108,6 +117,9 @@ export class GeometryLine extends Geometry {
}
}

/**
* A SurrealQL polygon geometry value.
*/
export class GeometryPolygon extends Geometry {
readonly polygon: [GeometryLine, ...GeometryLine[]];

Expand Down Expand Up @@ -153,6 +165,9 @@ export class GeometryPolygon extends Geometry {
}
}

/**
* A SurrealQL multi-point geometry value.
*/
export class GeometryMultiPoint extends Geometry {
readonly points: [GeometryPoint, ...GeometryPoint[]];

Expand Down Expand Up @@ -193,6 +208,9 @@ export class GeometryMultiPoint extends Geometry {
}
}

/**
* A SurrealQL multi-line geometry value.
*/
export class GeometryMultiLine extends Geometry {
readonly lines: [GeometryLine, ...GeometryLine[]];

Expand Down Expand Up @@ -231,6 +249,9 @@ export class GeometryMultiLine extends Geometry {
}
}

/**
* A SurrealQL multi-polygon geometry value.
*/
export class GeometryMultiPolygon extends Geometry {
readonly polygons: [GeometryPolygon, ...GeometryPolygon[]];

Expand Down Expand Up @@ -275,6 +296,9 @@ export class GeometryMultiPolygon extends Geometry {
}
}

/**
* A SurrealQL geometry collection value.
*/
export class GeometryCollection extends Geometry {
readonly collection: [Geometry, ...Geometry[]];

Expand Down
30 changes: 16 additions & 14 deletions src/data/types/range.ts
Original file line number Diff line number Diff line change
@@ -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>,
Expand All @@ -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}`;
}
}
Expand All @@ -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,
Expand Down Expand Up @@ -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}`;
}
}
Expand All @@ -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;

Expand Down
53 changes: 12 additions & 41 deletions src/data/types/recordid.ts
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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;
Expand All @@ -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;

Expand Down Expand Up @@ -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;

Expand All @@ -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);
}
3 changes: 3 additions & 0 deletions src/data/types/table.ts
Original file line number Diff line number Diff line change
@@ -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;

Expand Down
3 changes: 3 additions & 0 deletions src/data/types/uuid.ts
Original file line number Diff line number Diff line change
@@ -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;

Expand Down
3 changes: 3 additions & 0 deletions src/data/value.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
/**
* A complex SurrealQL value type
*/
export abstract class Value {
/**
* Compare equality with another value.
Expand Down
1 change: 1 addition & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading