Required dependencies

# No external runtime dependencies are declared in package.json.
# The source is self-contained. Node.js built-ins (net, tls, crypto, fs)
# are used via the nodeCrypto.ts / conUtils.server.ts platform split.
npm install typescript

If targeting Node.js with TLS connections, ensure Node.js 18+ is installed (native tls module required). No native addons, no pod install, no Android linking.

Project setup

1. Copy the source/ directory into your project, for example at src/gel/.

2. Configure tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "paths": {
      "gel": ["./src/gel/index.node.ts"],
      "gel/*": ["./src/gel/*"]
    }
  }
}

3. Set connection environment variables (choose one approach):

# DSN form
export GEL_DSN="gel://user:password@localhost:5656/mydb"

# Or individual variables
export GEL_HOST=localhost
export GEL_PORT=5656
export GEL_USER=myuser
export GEL_PASSWORD=secret
export GEL_DATABASE=mydb
export GEL_TLS_SECURITY=strict   # insecure | no_host_verification | strict | default

4. In code, import from ./src/gel/index.node.ts (or via the path alias gel).

Public API

Capabilities (enum, baseConn.ts)

export enum Capabilities {
  NONE = 0,
  // further members defined in baseConn.ts
}

Used to declare which server capabilities a query requires (e.g. DDL, persistent, transaction). Pass when constructing low-level query options to control what the server is permitted to execute.

TlsSecurity / validTlsSecurityValues (conUtils.ts)

export type TlsSecurity = "insecure" | "no_host_verification" | "strict" | "default";
export const validTlsSecurityValues: readonly TlsSecurity[];
export function isValidTlsSecurityValue(candidate: unknown): candidate is TlsSecurity;

Use isValidTlsSecurityValue to validate user-supplied TLS configuration before passing it into connection resolution. Prefer "strict" in production; use "insecure" only in local dev with self-signed certificates.

Options / IsolationLevel (options.ts)

export class Options { /* retry, transaction, warning config */ }
export enum IsolationLevel { /* Serializable, ... */ }

Options is the immutable configuration object threaded through every query and transaction. Create a customized instance to set retry rules, isolation level, or a warning handler, then pass it to the client via withRetryOptions / withTransactionOptions.

Transaction (transaction.ts)

export class Transaction { /* implements Executor */ }

Represents an active database transaction. Obtained inside the callback passed to client.transaction(). Provides the same query methods as the top-level client but scoped to the transaction.

GelError (errors/base.ts) and the full error hierarchy (errors/index.ts)

export class GelError extends Error { get code(): number; }
export class QueryError extends GelError { }
export class ConstraintViolationError extends QueryError { }
// ... many more

Catch GelError at the top level or narrow to specific subclasses for domain-level error handling.

Working examples

Scenario - Basic query execution

Import the Node.js client, create a pool, run a query, and close cleanly.

import { createClient } from "./src/gel/index.node";

async function main() {
  const client = createClient(); // reads GEL_DSN or GEL_HOST/PORT/etc.

  const result = await client.query<{ id: string; name: string }>(
    "SELECT Person { id, name } FILTER .name = <str>$name",
    { name: "Alice" }
  );

  console.log(result); // Array<{ id: string; name: string }>
  await client.close();
}

main().catch(console.error);

Scenario - Transaction with retry

Use client.transaction() for operations that must be atomic. The library automatically retries on serialization conflicts according to the configured RetryOptions.

import { createClient } from "./src/gel/index.node";
import { IsolationLevel } from "./src/gel/options";

const client = createClient().withTransactionOptions({
  isolation: IsolationLevel.Serializable,
  readonly: false,
  deferrable: false,
});

await client.transaction(async (tx) => {
  const [account] = await tx.query<{ balance: number }>(
    "SELECT Account { balance } FILTER .id = <uuid>$id",
    { id: "00000000-0000-0000-0000-000000000001" }
  );

  if (account.balance < 100) throw new Error("Insufficient funds");

  await tx.execute(
    "UPDATE Account FILTER .id = <uuid>$id SET { balance := .balance - 100 }",
    { id: "00000000-0000-0000-0000-000000000001" }
  );
});

Scenario - Error handling by type

Narrow caught errors to specific Gel error classes to handle constraint violations distinctly from connection failures.

import { createClient } from "./src/gel/index.node";
import { ConstraintViolationError, GelError } from "./src/gel/errors";

const client = createClient();

async function createUser(email: string) {
  try {
    await client.querySingle(
      "INSERT User { email := <str>$email }",
      { email }
    );
  } catch (err) {
    if (err instanceof ConstraintViolationError) {
      console.error("Email already registered:", email);
      return null;
    }
    if (err instanceof GelError) {
      console.error("Database error code", err.code.toString(16), err.message);
    }
    throw err;
  }
}

Scenario - Validate TLS security from environment

import { isValidTlsSecurityValue } from "./src/gel/conUtils";

const tlsSecurity = process.env.GEL_TLS_SECURITY;
if (tlsSecurity !== undefined && !isValidTlsSecurityValue(tlsSecurity)) {
  throw new Error(
    `Invalid GEL_TLS_SECURITY value: "${tlsSecurity}". ` +
    `Must be one of: insecure, no_host_verification, strict, default`
  );
}

File walkthrough

• baseClient.ts - Implements ClientConnectionHolder and BaseClientPool; manages connection lifecycle, pooling, and routes queries to raw connections.
• baseConn.ts - Binary protocol state machine; encodes/decodes messages, handles authentication handshake, exports Capabilities enum and protocol version constants.
• browserClient.ts - Thin subclass wiring the fetch-based transport for use in browser/edge environments.
• browserCrypto.ts - Adapts the Web Crypto API to the interface expected by SCRAM authentication.
• codecTypeRegistry.ts - Initializes and exports the global codec registry with all built-in type codecs registered.
• conUtils.ts - Parses DSNs, validates TLS settings, merges environment variables, exports Address, TlsSecurity, and config resolution logic.
• conUtils.server.ts - Node.js-only: discovers project credentials files and resolves connection from the filesystem.
• credentials.ts - Reads and validates .gel/credentials/*.json credential files.
• cryptoUtils.ts - Low-level HMAC/SHA-256 helpers shared by SCRAM implementations.
• fetchConn.ts - HTTP transport connection, used by the browser/edge client.
• httpScram.ts - SCRAM-SHA-256 authentication flow over HTTP for the fetch-based transport.
• ifaces.ts - Canonical interface and enum definitions (Executor, Cardinality, OutputFormat, Language, QueryArgs).
• index.browser.ts / index.node.ts / index.shared.ts - Platform-specific and shared entry points; control what is re-exported to consumers.
• nodeClient.ts - Node.js TCP/TLS client; constructs native socket connections.
• nodeCrypto.ts - Wraps Node.js crypto module for SCRAM.
• options.ts - Options (immutable config), IsolationLevel, retry/transaction/warning handler types.
• platform.ts - Detects runtime environment (Node.js vs. browser vs. edge).
• rawConn.ts - Wraps baseConn for pool use; manages checked-out connection state.
• retry.ts - retryingConnect helper and ConnectWithTimeout for connection establishment with backoff.
• scram.ts - Full SCRAM-SHA-256 authentication implementation.
• systemUtils.ts - Environment variable reading, home directory lookup.
• transaction.ts - Transaction (public API) and TransactionImpl (internal); wraps a connection holder in transaction semantics.
• typeutil.ts - TypeScript conditional/utility types used internally and by codegen.
• utils.ts - versionGreaterThan, versionGreaterThanOrEqual, sleep, and other small helpers.
• codecs/ - One file per Gel scalar/composite type (array, bool, bytes, datetime, enum, JSON, range, tuple, UUID, pgvector, PostGIS, etc.); each exports a codec class implementing ICodec.
• datatypes/ - JavaScript class representations of Gel types returned from the database (e.g. LocalDate, Duration, Range, Memory, Vector).
• errors/ - Auto-generated error class hierarchy rooted at GelError; errors/resolve.ts maps server error codes to classes.
• primitives/ - ReadBuffer/WriteBuffer for binary framing, LRU cache, async event, LIFO/FIFO queues, CRC-HQX.
• reflection/ - Schema introspection query runners, analyzeQuery, reserved keyword lists, and enums used by codegen.

Common pitfalls and fixes

• Missing GEL_DSN or host env vars at runtime: createClient() will throw InterfaceError immediately; set at least GEL_DSN or GEL_HOST + GEL_PORT + GEL_USER + GEL_PASSWORD + GEL_DATABASE.
• ESM/CJS interop: The source uses export * and named exports throughout; if bundling with CommonJS, set "module": "CommonJS" in tsconfig or use a bundler transform - do not mix require() and import for the same module.
• Platform split not respected: Never import from index.node.ts in a browser bundle or vice versa; use index.browser.ts for fetch-based environments, index.node.ts for Node.js.
• TLS self-signed cert in dev: Set GEL_TLS_SECURITY=insecure or no_host_verification; leaving it as strict (default) will reject self-signed development server certs.
• TypeScript moduleResolution: Must be "NodeNext" or "Bundler" - older "node" resolution will fail to resolve .ts extension imports used internally.
• Protocol version mismatch: PROTO_VER = [3, 0], PROTO_VER_MIN = [0, 9]; connecting to a Gel server older than 0.9 will throw UnsupportedProtocolVersionError.

Vibe-coding prompt template

I have the Gel JS client library core source at `src/gel/` in my project.
The integration guide is at `USAGE.md`.
The upstream package is `edgedb-js` (published as `gel` on npm).

Please help me integrate this source into my Node.js/TypeScript project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Set up the tsconfig `paths` alias so `gel` resolves to `src/gel/index.node.ts`.
3. Create a `src/db.ts` module that initializes a single shared client instance,
   reads connection config from environment variables, and exports the client.
4. Add query helper functions for the following operations: [DESCRIBE YOUR USE CASES].
5. Add a `src/db.transaction.ts` module demonstrating a multi-step transaction
   with automatic retry using `client.transaction()`.
6. Handle `GelError` and its subclasses (especially `ConstraintViolationError`)
   at the service layer with appropriate HTTP status codes.
7. Do not install the npm `gel` package - use only the source in `src/gel/`.
8. Show me the complete file contents for every file you create or modify.

License and credit

The source is licensed under the Apache License 2.0. See the LICENSE file in the upstream repository or source/ if present.

Upstream repository: geldata/gel-js Upstream npm package: gel

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Keycloak Identity and Access Management Platform

Automation, Utilities & Developer Tools

無料