@spanql/ql-lib

Isomorphic query serialization, DSL parsing, and GNS matrix mapping utilities for SpanQL.

This is the low-level, zero-dependency engine of the SpanQL framework. It can run in any JavaScript or TypeScript environment—including browsers, servers, edge workers (Cloudflare Workers, Vercel Edge), and serverless environments—without modifications.

Installation

Install via npm:

npm install @spanql/ql-lib

Key Features

1. Deterministic GNS Registry: Maps complex hierarchical selection paths to indexed bitmask slots based on a schema mapping config.
2. Textual DSL Parser: Tokenizes and parses YAML-like indented queries into a query Abstract Syntax Tree (AST).
3. Symmetrical Serialization: Symmetrical serialization of queries into compact, URL-safe wire payloads:
   • r: Root entity context ID.
   • q: Base64-encoded topology bitmask.
   • p: Serialized parameter maps.
4. Strict Schema Verification: Verifies schema structures and enforces character whitelist guards and reserved words constraints.

Core API Reference

1. GNSRegistry

The GNSRegistry maintains a static slot allocation map of attributes, relationships, and modifiers up to a certain recursion depth.

import { GNSRegistry } from '@spanql/ql-lib';

const schemaConfig = {
  author: {
    id: 'ID',
    name: 'string',
    books: '[book]'
  },
  book: {
    id: 'ID',
    title: 'string',
    author: 'author'
  }
};

const gns = new GNSRegistry(schemaConfig, {
  rootContextIds: { author: 1, book: 2 }
});

// Lookup slot index of a selection path starting at a root context
const slotIdx = gns.lookup('author.books.title', 'author'); 
console.log(slotIdx); // -> unique integer index

// Reverse lookup of slot index back to path
const path = gns.revLookup(slotIdx, 'author');
console.log(path); // -> 'author.books.title'

2. DSL Parsing

The parseSpanQL utility converts textual query representation into an unhydrated AST.

import { parseSpanQL } from '@spanql/ql-lib';

const queryText = `
author:
  name
  books:
    title
    _limit: 5
`;

const ast = parseSpanQL(queryText);
console.log(ast.root); // -> "author"
console.log(ast.entries); // -> array of query nodes

3. Symmetrical Query Serialization

Convert logical queries into wire format parameters, and vice versa.

Encoding (Query AST/JSON -> URL parameters)

Use encodeQuery to serialize selections and parameters.

import { encodeQuery } from '@spanql/ql-lib';

const queryInput = {
  root: 'author',
  nodes: [
    { path: 'author.name' },
    { path: 'author.books.title', value: 'Dune' }
  ]
};

const wireParams = encodeQuery(queryInput, gns);
console.log(wireParams);
// -> { r: 1, q: "...", p: "[...]" }

Decoding (URL parameters -> Query tree representation)

Use decodeQuery to inflate wire parameters back to a structured Query Tree on the gateway server.

import { decodeQuery } from '@spanql/ql-lib';

const wirePayload = { r: 1, q: "...", p: "[...]" };
const queryTree = decodeQuery(wirePayload, gns);

4. Schema Verification

Ensure that the schema configuration is syntactically sound and adheres to naming guards.

import { validateSchemaConfig } from '@spanql/ql-lib';

try {
  validateSchemaConfig(schemaConfig);
  console.log('Schema is valid.');
} catch (err) {
  console.error('Validation failed:', err.message);
}

File Structure

For full architectural details of the internals of this package, refer to FILE_STRUCTURE.md.