Database

ValueProxy

The ValueProxy<T> class acts as a proxy to a database value. Operations on a ValueProxy are not executed immediately but are recorded as query stages. ValueProxy objects appear inside callback functions for map, filter, do, update, join, and other query methods.

Class Definition

ValueProxy provides type-specific methods based on the underlying value type. The available operations are organized by category.

Create a ValueProxy

ValueProxy instances are created automatically when you use callback-based query methods. You can also create one from a constant value:

import { ValueProxy } from "@antelopejs/interface-database";

const constant = ValueProxy.constant(42);
const strConst = ValueProxy.constant("hello");

General Operations

These methods are available on all ValueProxy types.

`default(value)`

Return the given value if the proxy is null.

const phone = user.key("phone").default("N/A");

`eq(value)` / `ne(value)`

Equality and inequality comparison.

const isActive = user.key("status").eq("active");
const isNotAdmin = user.key("role").ne("admin");

`and(value)` / `or(value)` / `not()`

Logical operators for combining boolean expressions.

const canAccess = user.key("active").and(user.key("verified"));
const isSpecial = user.key("role").eq("admin").or(user.key("plan").eq("premium"));
const isInactive = user.key("active").not();

`cast<U>()`

Change the TypeScript type without runtime conversion.

Number Operations

Available when the proxy wraps a numeric value.

Arithmetic

const next = age.add(1);
const diff = total.sub(discount);
const doubled = price.mul(2);
const half = amount.div(2);
const remainder = count.mod(10);

Rounding

const rounded = score.round();
const ceiling = value.ceil();
const floored = value.floor();

Bitwise

const bitwiseAnd = flags.band(0xff);
const bitwiseOr = flags.bor(0x01);
const bitwiseXor = flags.bxor(mask);
const bitwiseNot = flags.bnot();
const shifted = flags.blshift(2);
const unshifted = flags.brshift(2);
const signPreserved = flags.brshiftPreserveSign(2);

Comparison Operations

Available for number, string, and Date proxy values.

const isAdult = age.gt(17);
const isMinor = age.le(17);
const isRecent = date.ge(new Date("2024-01-01"));
const isBefore = date.lt(deadline);

Method	Description
`gt(v)`	Greater than
`ge(v)`	Greater than or equal
`lt(v)`	Less than
`le(v)`	Less than or equal

Date Operations

Available when the proxy wraps a Date value. All date component methods accept an optional timezone parameter.

Arithmetic

const threeDaysLater = created.add(3 * 24 * 60 * 60);
const elapsed = now.sub(created); // difference in seconds

Components

const y = created.year();
const m = created.month();
const d = created.day();
const dow = created.dayofweek();
const doy = created.dayofyear();
const h = created.hours();
const min = created.minutes();
const sec = created.seconds();
const tod = created.timeofday(); // seconds since midnight
const epoch = created.epoch();   // seconds since UNIX epoch

Range Check

const inRange = created.during(
  ValueProxy.constant(new Date("2024-01-01")),
  ValueProxy.constant(new Date("2025-01-01")),
);

String Operations

Available when the proxy wraps a string value.

const upper = name.upcase();
const lower = name.downcase();
const parts = email.split("@");
const full = first.concat(last);
const len = name.strlen();
const matches = email.match("^.*@gmail\\.com$");

Method	Description
`upcase()`	Convert to uppercase
`downcase()`	Convert to lowercase
`split(sep, max?)`	Split by separator
`concat(other)`	Concatenate with another string
`strlen()`	Number of Unicode codepoints
`match(regex)`	Test against a regex pattern

Array Operations

Available when the proxy wraps an array value.

const first = tags.index(0);
const hasAdmin = tags.includes("admin");
const sub = tags.slice(0, 3);
const upper = tags.map((t) => t.upcase());
const long = tags.filter((t) => t.strlen().gt(5));
const empty = tags.isempty();
const len = tags.count();
const total = scores.sum();
const average = scores.avg();
const lowest = scores.min();
const highest = scores.max();

Method	Description
`index(n)`	Element at position `n`
`includes(val)`	Check if the array contains a value
`slice(s, e?)`	Extract a sub-array
`map(fn)`	Transform each element
`filter(fn)`	Keep elements matching a predicate
`isempty()`	Check if the array is empty
`count()`	Number of elements
`sum()`	Sum of numeric elements
`avg()`	Average of numeric elements
`min()`	Minimum of numeric elements
`max()`	Maximum of numeric elements

Object Operations

Available when the proxy wraps a record/object value.

const email = user.key("email");
const emailOrDefault = user.key("email", "[email protected]");
const merged = user.merge({ lastSeen: new Date() });
const fieldNames = user.keys();
const fieldValues = user.values();
const hasRequired = user.hasfields("email", "name");

Method	Description
`key(k, def?)`	Access a field, with optional default
`merge(other)`	Merge with another object
`keys()`	Array of field names
`values()`	Array of field values
`hasfields(...fs)`	Check if all specified fields exist

Compose Expressions

ValueProxy methods are chainable, enabling complex expressions within query callbacks:

const result = await users.filter((user) =>
  user.key("age").ge(18)
    .and(user.key("status").eq("active"))
    .and(
      user.key("role").eq("admin")
        .or(user.key("plan").eq("premium")),
    ),
);

Datum

The Datum<T> class represents a single value in the query system. It extends Query<T> and provides methods for accessing fields, applying transformations, and performing foreign key lookups on individual values.

Operations

This section covers practical operations you can perform with the AQL interface. These guides walk through schema management, table access, document CRUD, index usage, filtering, and foreign key lookups.