Initial stubs for a Typescript WOQL AST

package.json

@@ -20,7 +20,7 @@
   "author": "kevin@terminusdb.com",
   "license": "Apache-2.0",
   "dependencies": {
-    "axios": "^0.25.0",
+    "axios": "1.6",
     "follow-redirects": "^1.14.8",
     "form-data": "^4.0.0",
     "jest": "^29.1.2",

ts-lib/stubs/WoqlObjectImpl.ts

@@ -0,0 +1,20 @@
+import { WoqlConfig } from "../types";
+import {
+  // WoqlInterface,
+  WoqlNodeValueExpression,
+} from "./WoqlObjectTypes";
+import * as woql from "./woql";
+
+export const convertToWoqlValueTerm = (term: string): WoqlNodeValueExpression => {
+  return {
+    "@type": "NodeValue",
+    variable: term,
+    renderLegacyWoql: () => term
+  };
+};
+
+export interface NamedParametricQueryConfiguration extends WoqlConfig {
+  bindParameters?: Array<string>;
+}
+
+export const WoqlAst = woql;

ts-lib/stubs/WoqlObjectImpl.unit.test.ts

@@ -0,0 +1,36 @@
+import WOQL from "../../lib/woql";
+import { WoqlAst } from "./WoqlObjectImpl";
+
+describe("Ensure sanity checks for WOQL functionality for VisualWoql implementation", () => {
+  it("should render a JSON object from a simple query with and and triples", () => {
+    const woqlAst = WoqlAst.and([WoqlAst.triple("s", "p", "o"), WoqlAst.triple("s", "p", "o")]);
+    const rendered = woqlAst.renderLegacyWoql().json();
+    const woqlRendered = WOQL.and(WOQL.triple("s", "p", "o"), WOQL.triple("s", "p", "o")).json();
+    expect(rendered).toStrictEqual(woqlRendered);
+  });
+
+  it("should render a JSON object from a simple query with variables", () => {
+    const woqlAst = WoqlAst.and([WoqlAst.triple("v:s", "v:p", "v:o"), WoqlAst.triple("v:s", "v:p", "v:o")]);
+    const rendered = woqlAst.renderLegacyWoql().json();
+    const woqlRendered = WOQL.and(WOQL.triple("v:s", "v:p", "v:o"), WOQL.triple("v:s", "v:p", "v:o")).json();
+    expect(rendered).toStrictEqual(woqlRendered);
+  });
+
+  it("should render a named query from the AST", () => {
+    const woqlAst = WoqlAst.namedQuery("", WoqlAst.triple("v:s", "v:p", "v:o"));
+    const rendered = woqlAst.renderLegacyWoql().json();
+    const woqlRendered = WOQL.triple("v:s", "v:p", "v:o").json();
+    expect(rendered).toStrictEqual(woqlRendered);
+  });
+
+  it("should render a named parametric query from the AST", () => {
+    const woqlAst = WoqlAst.namedParametricQuery("", WoqlAst.triple("v:s", "v:p", "v:o"), {
+      bindParameters: ["v:myVar"],
+    });
+    const rendered = woqlAst.renderBoundLegacyWoql("variableValue").json();
+    const woqlRendered = WOQL.and(WOQL.eq("v:myVar", "variableValue"), WOQL.triple("v:s", "v:p", "v:o")).json();
+    expect(rendered).toStrictEqual(woqlRendered);
+  });
+
+  it("should render a named parametric query from the AST", () => {});
+});

ts-lib/stubs/WoqlObjectTypes.ts

@@ -0,0 +1,70 @@
+import { WoqlConfig } from "../types";
+import { NamedParametricQueryConfiguration } from "./WoqlObjectImpl";
+
+export type WoqlTerm = "NamedParametricQuery" | "NamedQuery" | "And" | "Select" | "Triple";
+export type WoqlQueryTerm = WoqlBaseSegment;
+
+export interface WoqlBaseSegment {
+  "@id"?: string;
+  "@type": unknown;
+  renderLegacyWoql: () => LegacyWoql;
+}
+
+// FIXME: The legacy WOQL is of type any...
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type LegacyWoql = any;
+
+export interface WoqlValueSegment {
+  "@id"?: string;
+  "@type": unknown;
+}
+
+export interface WoqlNodeValueVariable extends WoqlNodeValueTemplate {
+  "@type": "NodeValue";
+  variable: string;
+}
+
+export interface WoqlNodeValueNode extends WoqlNodeValueTemplate {
+  "@type": "NodeValue";
+  node: string;
+}
+
+export type WoqlNodeValueExpression = WoqlNodeValueNode | WoqlNodeValueVariable;
+
+// type WoqlNodeValueKeys = "variable" | "node"
+
+export interface WoqlNodeValueTemplate extends WoqlValueSegment {
+  // FIXME: Needs to be checked, and inserted before submitting, perhaps in the future, accepted on the server side
+  parameterIndex?: number;
+  renderLegacyWoql: () => LegacyWoql;
+}
+
+export interface WoqlAnd extends WoqlBaseSegment {
+  "@type": "And";
+  and: Array<WoqlBaseSegment>;
+}
+
+export interface WoqlSelect extends WoqlBaseSegment {
+  "@type": "Select";
+}
+
+export interface WoqlTriple extends WoqlBaseSegment {
+  "@type": "Triple";
+  subject: WoqlNodeValueExpression;
+  predicate: WoqlNodeValueExpression;
+  object: WoqlNodeValueExpression;
+}
+
+export interface WoqlNamedParametricQuery extends WoqlBaseSegment {
+  "@type": "NamedParametricQuery";
+  name: string;
+  query: WoqlQueryTerm;
+  parameters: Array<string>;
+  renderBoundLegacyWoql: (...args: Array<string>) => LegacyWoql;
+}
+
+export interface WoqlNamedQuery extends WoqlBaseSegment {
+  "@type": "NamedQuery";
+  name: string;
+  query: WoqlQueryTerm;
+}

ts-lib/stubs/woql/and.ts

@@ -0,0 +1,15 @@
+import { WoqlConfig } from "../../types";
+import WOQL from "../../../lib/woql";
+import {
+  WoqlAnd,
+  WoqlBaseSegment
+} from "../WoqlObjectTypes";
+
+export const and = (and: Array<WoqlBaseSegment>, config?: WoqlConfig): WoqlAnd => {
+  return {
+    ...(config?.id ? { "@id": `And/${config?.id}` } : {}),
+    "@type": "And",
+    and,
+    renderLegacyWoql: () => WOQL.and(...and.map(andSegment => andSegment.renderLegacyWoql()))
+  };
+};

ts-lib/stubs/woql/index.ts

@@ -0,0 +1,4 @@
+export { and } from "./and";
+export { triple } from "./triple";
+export { namedQuery } from "./namedQuery";
+export { namedParametricQuery } from "./namedParametricQuery";

ts-lib/stubs/woql/namedParametricQuery.ts

@@ -0,0 +1,31 @@
+import WOQL from "../../../lib/woql";
+import { WoqlBaseSegment, WoqlNamedParametricQuery } from "../WoqlObjectTypes";
+import { NamedParametricQueryConfiguration } from "../WoqlObjectImpl";
+
+export const namedParametricQuery = (
+  name: string,
+  woql: WoqlBaseSegment,
+  config?: NamedParametricQueryConfiguration
+): WoqlNamedParametricQuery => {
+  const parameters = config?.bindParameters ?? [];
+  return {
+    "@id": config?.id,
+    "@type": "NamedParametricQuery",
+    name,
+    query: woql,
+    parameters: parameters,
+    // When you need to use it outside of TerminusDB, remember to bind the parameter to the positional values!
+    renderLegacyWoql: () => woql.renderLegacyWoql(),
+    renderBoundLegacyWoql: (...args: Array<string>) => {
+      if (args.length !== parameters.length) {
+        throw new Error(
+          "The number of arguments must match the number of parameters"
+        );
+      }
+      return WOQL.and(
+        ...args.map((arg, index) => WOQL.eq(parameters[index], arg)),
+        woql.renderLegacyWoql()
+      );
+    }
+  };
+};

ts-lib/stubs/woql/namedQuery.ts

@@ -0,0 +1,16 @@
+import { WoqlConfig } from "../../types";
+import { WoqlBaseSegment, WoqlNamedQuery } from "../WoqlObjectTypes";
+
+export const namedQuery = (
+  name: string,
+  woql: WoqlBaseSegment,
+  config?: WoqlConfig
+): WoqlNamedQuery => {
+  return {
+    "@id": config?.id,
+    "@type": "NamedQuery",
+    name,
+    query: woql,
+    renderLegacyWoql: () => woql.renderLegacyWoql()
+  };
+};

ts-lib/stubs/woql/triple.ts

@@ -0,0 +1,31 @@
+import { WoqlConfig } from "../../types";
+import WOQL from "../../../lib/woql";
+import {
+  WoqlNodeValueExpression,
+  WoqlTriple
+} from "../WoqlObjectTypes";
+import { convertToWoqlValueTerm } from "../WoqlObjectImpl";
+
+export const triple = (
+  subject: string | WoqlNodeValueExpression,
+  predicate: string | WoqlNodeValueExpression,
+  object: string | WoqlNodeValueExpression,
+  config?: WoqlConfig
+): WoqlTriple => {
+  return {
+    ...(config?.id ? { "@id": `Triple/${config?.id}` } : {}),
+    "@type": "Triple",
+    subject: typeof subject === "string" ? convertToWoqlValueTerm(subject) : subject,
+    predicate: typeof predicate === "string"
+      ? convertToWoqlValueTerm(predicate)
+      : predicate,
+    object: typeof object === "string" ? convertToWoqlValueTerm(object) : object,
+    renderLegacyWoql: () => WOQL.triple(
+      typeof subject === "string" ? subject : subject.renderLegacyWoql(),
+      typeof predicate === "string"
+        ? predicate
+        : predicate.renderLegacyWoql(),
+      typeof object === "string" ? object : object.renderLegacyWoql()
+    )
+  };
+};

ts-lib/types.tsx

@@ -0,0 +1,28 @@
+export type TerminusPropertySingle = string | number | boolean | TerminusResponseObject;
+export type TerminusPropertyValue = TerminusPropertySingle | Array<TerminusPropertySingle> | Record<string, unknown> | object | Array<object>;
+export type TerminusResponseObject = null | TerminusReadObject;
+
+export interface WoqlConfig {
+  id?: string;
+}
+
+export interface TerminusReadObject {
+  "@id"?: string;
+  "@type": string;
+  [propName: string]: TerminusPropertyValue | undefined;
+}
+
+export interface TerminusReadObjectWithId {
+  "@id": string;
+  "@type": string;
+  [propName: string]: TerminusPropertyValue | undefined;
+}
+
+export interface WoqlObject extends TerminusReadObject {
+  "@type": "And" | "Triple";
+}
+
+export interface WoqlParameter {
+  key: string,
+  value: string,
+}