@valbuild/core 0.12.0 → 0.13.0

package/jest.config.js

@@ -0,0 +1,4 @@
+/** @type {import("jest").Config} */
+module.exports = {
+  preset: "../../jest.preset",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "jest",

package/src/Json.ts

@@ -0,0 +1,4 @@
+export type Json = JsonPrimitive | JsonObject | JsonArray;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = readonly Json[];
+export type JsonObject = { readonly [key in string]: Json };

package/src/expr/README.md

@@ -0,0 +1,193 @@
+# Visp
+
+Visp (as in Val Lisp or whisk in Norwegian) is a Lisp used to serialize Val `Selector`s.
+
+It is an INTERNAL language - it is NOT designed to be used by end-users.
+This document is architectural overview for this INTERNAL language - it is documentation for developers working on Val.
+
+Visp exists since Val clients must be able to execute remote `Selector`s.
+See the docs for remote `Schema`s for more about this.
+
+The design goals are as follows:
+
+- evaluate to `Val` objects
+- easy to parse and serialize
+- easy to evaluate in JavaScript
+- readable by Vals developers (for internal debugging)
+- stable language semantics to avoid breaking changes as Visp is part of the (internal) API versioning
+- does not support more functionality than what is required to serialize `Selector`s
+
+The non-goals are:
+
+- Visp does not need to be convenient to write - `Selector`s are used to write it
+- Visp does not need to be easily understandable by end-users of Val
+
+## Syntax
+
+Visp is a Lisp which only can evaluate one expression at a time.
+
+Read more about how it works in sections that follows.
+
+### Property access
+
+```visp
+('title' foo)
+```
+
+corresponds to:
+
+```js
+foo["title"];
+```
+
+There are no numbers in Visp, so arrays are indexed in the same way:
+
+```visp
+('0' foo)
+```
+
+corresponds to:
+
+```js
+foo["0"]; // same as foo[0]
+```
+
+### Function calls
+
+Function calls are similar to property access, but with arguments separated by whitespace:
+
+```visp
+(fnname foo arg1 arg2)
+```
+
+corresponds to:
+
+```js
+foo["fnname"](arg1, arg2); // same as foo.fname(arg1, arg2)
+```
+
+#### Higher order functions
+
+Higher order functions must be prefixed with the `!` character.
+Arguments can be accessed using the `@` character. The `@` must be suffixed with indexes, e.g. `@[0,0]`, the first one corresponding to the stack depth and the second corresponds to index of the argument list.
+
+```visp
+!(map foo @[0,0])
+```
+
+corresponds to:
+
+```js
+foo.map((v) => v);
+```
+
+Here we access the second argument of a function:
+
+```visp
+!(map foo @[0,1])
+```
+
+corresponds to:
+
+```js
+foo.map((_, i) => i);
+```
+
+This example shows how higher functions and arguments can be nested:
+
+```visp
+!(map foo !(map @[0,0] (slice @[1,0] @[0,1])))
+```
+
+corresponds to:
+
+```js
+foo.map((v, i) => v.map((j) => j.slice(i)));
+```
+
+### Literals
+
+Visp only supports string literals.
+
+Example:
+
+```visp
+'foo'
+```
+
+corresponds to:
+
+```js
+"foo";
+```
+
+### String templates
+
+Val has support for string templates similar to JavaScript.
+They are denoted using single quotes `'` (as string literal), but can inject expressions using `${}`.
+
+Example:
+
+```visp
+'foo ${('title' obj)} bar'
+```
+
+corresponds to:
+
+```js
+`foo ${obj["title"]} bar`;
+```
+
+### Special symbols
+
+### `()`
+
+The `()` symbol evaluates to `undefined`.
+
+#### `@`
+
+This symbol can be used to access arguments in [higher order functions](#higher-order-functions).
+
+### `!`
+
+This is a prefix to a [higher order function](#higher-order-functions).
+
+### val
+
+The `val` symbol is used to access data from a Val module.
+
+Example:
+
+```visp
+(val '/foo/bar`)
+```
+
+Returns the `Source` of a Val module of id `/foo/bar`.
+
+### json
+
+The `json` symbol is used to parse json strings.
+
+Example:
+
+```visp
+(json '{"foo": "bar"}')
+```
+
+To create numbers, lists etc, the `json` symbol can be used.
+
+It is also possible to use `json` with string templates:
+
+```visp
+(json '{ "foo": ${('title' obj)} }')
+```
+
+corresponds to:
+
+```js
+JSON.parse(`{ "foo": ${obj["title"]} }`);
+```
+
+### More
+
+More examples can be found in the [eval.test](eval.test.ts)

package/src/expr/eval.test.ts

@@ -0,0 +1,202 @@
+import { pipe, result } from "../../fp";
+import { Path } from "../selector";
+import { newSelectorProxy, selectorToVal } from "../selector/SelectorProxy";
+import { Source } from "../source";
+import { SourcePath } from "../val";
+import { evaluate } from "./eval";
+import { parse } from "./parser";
+
+const sources = {
+  "/app/text": "text1",
+  "/numbers": [0, 1, 2],
+  "/articles": [{ title: "title1" }, { title: "title2" }],
+  "/app/blogs": [
+    { title: "blog1", text: "text1" },
+    { title: "blog2", text: "text2" },
+  ],
+};
+
+const EvalTestCases: {
+  expr: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  expected: result.Result<{ val: Source; [Path]: any }, any>;
+  focus?: boolean; // use focus to specify a single test case
+}[] = [
+  {
+    expr: `'hello world'`,
+    expected: result.ok({ val: "hello world", [Path]: undefined }),
+  },
+  {
+    expr: `(val '/numbers')`,
+    expected: result.ok({ val: [0, 1, 2], [Path]: "/numbers" }),
+  },
+  {
+    expr: `('hello world')`,
+    expected: result.ok({ val: "hello world", [Path]: undefined }),
+  },
+  {
+    expr: `()`,
+    expected: result.ok({ val: null, [Path]: undefined }),
+  },
+  {
+    expr: `(eq 'value' 'show me')`,
+    expected: result.ok({ val: false, [Path]: undefined }),
+  },
+  {
+    expr: `(eq 'value' 'value')`,
+    expected: result.ok({ val: true, [Path]: undefined }),
+  },
+  {
+    expr: `!(andThen 'value' 'show me')`,
+    expected: result.ok({ val: "show me", [Path]: undefined }),
+  },
+  {
+    expr: `!(andThen '' ('do NOT show me'))`,
+    expected: result.ok({ val: "", [Path]: undefined }),
+  },
+  {
+    expr: `!(andThen 'text1' @[0,0])`,
+    expected: result.ok({ val: "text1", [Path]: undefined }),
+  },
+  {
+    expr: `(json '1')`,
+    expected: result.ok({ val: 1, [Path]: undefined }),
+  },
+  {
+    expr: `(json '"1"')`,
+    expected: result.ok({ val: "1", [Path]: undefined }),
+  },
+  {
+    expr: `(json '{"foo": "bar"}')`,
+    expected: result.ok({ val: { foo: "bar" }, [Path]: undefined }),
+  },
+  {
+    expr: `(json '\${(json '1')}')`,
+    expected: result.ok({ val: 1, [Path]: undefined }),
+  },
+  {
+    expr: `(json '\${(json '"1"')}')`,
+    expected: result.ok({ val: "1", [Path]: undefined }),
+  },
+  {
+    expr: `(json '{"foo": \${(json '"1"')}}')`,
+    expected: result.ok({
+      val: {
+        foo: "1",
+      },
+      [Path]: undefined,
+    }),
+  },
+  {
+    expr: `(json '\${(val '/numbers')}')`,
+    expected: result.ok({
+      val: sources["/numbers"],
+      [Path]: "/numbers",
+    }),
+  },
+  {
+    expr: `('test' (json '{ "test": \${((json '0') (val '/numbers'))} }'))`,
+    expected: result.ok({
+      val: 0,
+      [Path]: "/numbers.0",
+    }),
+  },
+  {
+    expr: `((json '1') ('foo' (json '{"foo": \${(val '/numbers')}}')))`,
+    expected: result.ok({ val: 1, [Path]: "/numbers.1" }),
+  },
+  {
+    expr: `(length (val '/numbers'))`,
+    expected: result.ok({
+      val: sources["/numbers"].length,
+      [Path]: undefined,
+    }),
+  },
+  {
+    expr: `('0' (val '/articles'))`,
+    expected: result.ok({
+      val: sources["/articles"][0],
+      [Path]: "/articles.0",
+    }),
+  },
+  {
+    expr: `!(map (val '/articles') @[0,0])`,
+    expected: result.ok({
+      val: sources["/articles"].map((v) => v),
+      [Path]: "/articles",
+    }),
+  },
+  {
+    expr: `('0' !(map (val '/articles') ('title' @[0,0])))`,
+    expected: result.ok({
+      val: sources["/articles"].map((v) => v["title"])[0],
+      [Path]: '/articles.0."title"',
+    }),
+  },
+  {
+    expr: `!(map (val '/articles') ('title' @[0,0]))`,
+    expected: result.ok({
+      val: sources["/articles"].map((v) => v["title"]),
+      [Path]: "/articles",
+    }),
+  },
+  {
+    expr: `(eq !(andThen (val '/app/text') ()) 'foo')`,
+    expected: result.ok({
+      val: false,
+      [Path]: undefined,
+    }),
+  },
+  {
+    expr: `!(filter (val '/app/blogs') (eq ('title' @[0,0]) 'blog1'))`,
+    expected: result.ok({
+      val: [
+        {
+          text: "text1",
+          title: "blog1",
+        },
+      ],
+      [Path]: "/app/blogs",
+    }),
+  },
+  {
+    expr: `(json '{"title": \${()}}')`,
+    expected: result.ok({
+      val: {
+        title: null,
+      },
+
+      [Path]: undefined,
+    }),
+  },
+];
+
+describe("eval", () => {
+  test.each(
+    EvalTestCases.filter(({ focus }) =>
+      EvalTestCases.some((v) => v.focus) ? focus : true
+    )
+  )('evaluate: "$expr"', ({ expr, expected }) => {
+    const parseRes = parse(expr);
+    if (result.isErr(parseRes)) {
+      return expect(parseRes).toHaveProperty("value");
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(
+      pipe(
+        evaluate(
+          parseRes.value,
+          (ref) => {
+            return newSelectorProxy(
+              sources[ref as keyof typeof sources],
+              ref as SourcePath
+            );
+          },
+          []
+        ),
+        result.map((v) => selectorToVal(v))
+      )
+    ).toStrictEqual(expected);
+  });
+  //
+});

package/src/expr/eval.ts

@@ -0,0 +1,248 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Call, Expr, StringLiteral, StringTemplate, Sym } from "./expr";
+import { Source } from "../source";
+import { result } from "../fp";
+import { Path, SourceOrExpr } from "../selector";
+import { newSelectorProxy } from "../selector/SelectorProxy";
+import { isSerializedVal, SourcePath } from "../val";
+
+export class EvalError {
+  constructor(public readonly message: string, public readonly expr: Expr) {}
+
+  toString() {
+    return `${this.message} in: ${this.expr.transpile()}`;
+  }
+}
+
+type LocalSelector<S extends Source> = {
+  readonly [key: string | number]:
+    | LocalSelector<Source>
+    | ((...args: any[]) => any);
+} & {
+  [SourceOrExpr]: S;
+  [Path]: SourcePath | undefined;
+};
+
+const MAX_STACK_SIZE = 100; // an arbitrary semi-large number
+function evaluateSync(
+  expr: Expr,
+  getSource: (ref: string) => LocalSelector<Source>,
+  stack: readonly LocalSelector<Source>[][]
+): LocalSelector<Source> {
+  // TODO: amount of evaluates should be limited?
+  if (stack.length > MAX_STACK_SIZE) {
+    throw new EvalError(
+      `Stack overflow. Final frames: ${stack
+        .slice(-10)
+        .map((frame, i) =>
+          frame.map((s, j) => `@[${i},${j}]: ${JSON.stringify(s)}`).join(", ")
+        )
+        .join(" -> ")}`,
+      expr
+    );
+  }
+  if (expr instanceof Call) {
+    if (expr.children[0] instanceof Sym) {
+      if (expr.children[0].value === "val") {
+        if (expr.isAnon) {
+          throw new EvalError("cannot call 'val' as anonymous function", expr);
+        }
+        if (expr.children[1] instanceof StringLiteral) {
+          return getSource(expr.children[1].value);
+        } else {
+          throw new EvalError(
+            "argument of 'val' must be a string literal",
+            expr
+          );
+        }
+      } else if (expr.children[0].value === "json") {
+        if (expr.children.length !== 2) {
+          throw new EvalError(
+            "must call 'json' with exactly one argument",
+            expr
+          );
+        }
+        const value = evaluateSync(expr.children[1], getSource, stack);
+
+        const valObj = value[SourceOrExpr];
+        const valPath = value[Path];
+        if (typeof valObj !== "string") {
+          throw new EvalError(
+            `cannot parse JSON: ${JSON.stringify(valObj)}, expected string`,
+            expr.children[1]
+          );
+        }
+        try {
+          const serialized = JSON.parse(valObj);
+          if (isSerializedVal(serialized)) {
+            return newSelectorProxy(serialized.val, serialized.valPath);
+          }
+          const parsedValue = newSelectorProxy(JSON.parse(valObj), valPath);
+          return parsedValue;
+        } catch (e) {
+          if (e instanceof SyntaxError) {
+            throw new EvalError(
+              `cannot parse JSON: ${valObj}, ${
+                e.message
+              } - value: ${JSON.stringify(value)}`,
+              expr.children[1]
+            );
+          }
+          throw e;
+        }
+      } else if (expr.children[0].value === "stringify") {
+        // TODO: remove stringify
+        if (expr.children.length !== 2) {
+          throw new EvalError(
+            "must call 'stringify' with exactly one argument",
+            expr
+          );
+        }
+        const res = evaluateSync(expr.children[1], getSource, stack);
+        return newSelectorProxy(JSON.stringify(res[SourceOrExpr]));
+      }
+    }
+    const prop = evaluateSync(expr.children[0], getSource, stack)[SourceOrExpr];
+    if (expr.children.length === 1) {
+      // TODO: return if literal only?
+      return newSelectorProxy(prop);
+    }
+    const obj = evaluateSync(expr.children[1], getSource, stack);
+    if (typeof prop !== "string" && typeof prop !== "number") {
+      throw new EvalError(
+        `cannot access ${JSON.stringify(obj)} with property ${JSON.stringify(
+          prop
+        )}: is not a string or number`,
+        expr
+      );
+    }
+
+    if (prop in obj) {
+      if (expr.isAnon) {
+        // anon functions:
+        const maybeFunction = obj[prop];
+        if (typeof maybeFunction !== "function") {
+          throw new EvalError(
+            `cannot access property ${JSON.stringify(prop)} of ${JSON.stringify(
+              obj
+            )}: required higher ordered function got ${typeof obj[prop]}`,
+            expr
+          );
+        }
+        if (expr.children[0] instanceof Sym) {
+          return maybeFunction((...args: any[]) => {
+            return evaluateSync(
+              expr.children[2],
+              getSource,
+              stack.concat([args])
+            );
+          });
+        } else {
+          throw new EvalError(
+            `cannot call an expression that is not a symbol, got: '${expr.children[0].type}'`,
+            expr
+          );
+        }
+      } else {
+        // non-anon functions:
+        if (expr.children[0] instanceof Sym) {
+          if (expr.children[0].value === "val") {
+            if (expr.children[1] instanceof StringLiteral) {
+              return getSource(expr.children[1].value);
+            } else {
+              throw new EvalError(
+                "argument of 'val' must be a string literal",
+                expr
+              );
+            }
+          }
+        }
+        const args = expr.children.slice(2);
+        if (args.length > 0) {
+          const maybeFunction = obj[prop];
+          if (typeof maybeFunction !== "function") {
+            throw new EvalError(
+              `cannot access property ${JSON.stringify(
+                prop
+              )} of ${JSON.stringify(obj)}: required function got ${typeof obj[
+                prop
+              ]}`,
+              expr
+            );
+          }
+          return maybeFunction(
+            ...args.map((arg) => evaluateSync(arg, getSource, stack))
+          );
+        }
+        const maybeValue = obj[prop];
+        if (typeof maybeValue === "function") {
+          throw new EvalError(
+            `cannot access property ${JSON.stringify(prop)} of ${JSON.stringify(
+              obj
+            )}: required value got ${typeof obj[prop]}`,
+            expr
+          );
+        }
+        return maybeValue;
+      }
+    }
+  } else if (expr instanceof Sym) {
+    if (expr.value.startsWith("@")) {
+      const [i, j, rest] = expr.value.slice(2, -1).split(",");
+      if (rest) {
+        throw new EvalError(`cannot access stack: too many indices`, expr);
+      }
+      const stackValue = stack[Number(i)]?.[Number(j)];
+      if (stackValue === undefined) {
+        throw new EvalError(`cannot access stack: out of bounds`, expr);
+      }
+      return stackValue;
+    } else if (expr.value === "()") {
+      return newSelectorProxy(null);
+    }
+    return newSelectorProxy(expr.value);
+  } else if (expr instanceof StringLiteral) {
+    return newSelectorProxy(expr.value);
+  } else if (expr instanceof StringTemplate) {
+    return newSelectorProxy(
+      expr.children
+        .map((child) => {
+          if (child instanceof Sym && child.value === "()") {
+            return "null";
+          }
+          const evalRes = evaluateSync(child, getSource, stack);
+          if (
+            child.type === "StringLiteral" ||
+            child.type === "StringTemplate"
+          ) {
+            return evalRes[SourceOrExpr];
+          }
+          if (Path in evalRes) {
+            // a selector, so serialize to Val
+            return JSON.stringify({
+              val: evalRes[SourceOrExpr],
+              valPath: evalRes[Path],
+            });
+          }
+          return JSON.stringify(evalRes[SourceOrExpr]);
+        })
+        .join("")
+    );
+  }
+  throw new EvalError(`could not evaluate`, expr);
+}
+
+export function evaluate(
+  expr: Expr,
+  source: (ref: string) => LocalSelector<Source>,
+  stack: readonly LocalSelector<Source>[][]
+): result.Result<LocalSelector<Source>, EvalError> {
+  try {
+    return result.ok(evaluateSync(expr, source, stack));
+  } catch (err) {
+    if (err instanceof EvalError) {
+      return result.err(err);
+    }
+    throw err;
+  }
+}