npm - @valbuild/core - Versions diffs - 0.12.0 → 0.13.1 - Mend

@valbuild/core 0.12.0 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (72) hide show

package/README.md +25 -37
package/jest.config.js +4 -0
package/package.json +1 -1
package/src/Json.ts +4 -0
package/src/expr/README.md +193 -0
package/src/expr/eval.test.ts +202 -0
package/src/expr/eval.ts +248 -0
package/src/expr/expr.ts +91 -0
package/src/expr/index.ts +3 -0
package/src/expr/parser.test.ts +158 -0
package/src/expr/parser.ts +229 -0
package/src/expr/repl.ts +93 -0
package/src/expr/tokenizer.test.ts +539 -0
package/src/expr/tokenizer.ts +117 -0
package/src/fetchVal.test.ts +164 -0
package/src/fetchVal.ts +211 -0
package/src/fp/array.ts +30 -0
package/src/fp/index.ts +3 -0
package/src/fp/result.ts +214 -0
package/src/fp/util.ts +52 -0
package/src/index.ts +55 -0
package/src/initSchema.ts +45 -0
package/src/initVal.ts +96 -0
package/src/module.test.ts +170 -0
package/src/module.ts +333 -0
package/src/patch/deref.test.ts +300 -0
package/src/patch/deref.ts +128 -0
package/src/patch/index.ts +11 -0
package/src/patch/json.test.ts +583 -0
package/src/patch/json.ts +304 -0
package/src/patch/operation.ts +74 -0
package/src/patch/ops.ts +83 -0
package/src/patch/parse.test.ts +202 -0
package/src/patch/parse.ts +187 -0
package/src/patch/patch.ts +46 -0
package/src/patch/util.ts +67 -0
package/src/schema/array.ts +52 -0
package/src/schema/boolean.ts +38 -0
package/src/schema/i18n.ts +65 -0
package/src/schema/image.ts +70 -0
package/src/schema/index.ts +46 -0
package/src/schema/literal.ts +42 -0
package/src/schema/number.ts +45 -0
package/src/schema/object.ts +67 -0
package/src/schema/oneOf.ts +60 -0
package/src/schema/richtext.ts +417 -0
package/src/schema/string.ts +49 -0
package/src/schema/union.ts +62 -0
package/src/selector/ExprProxy.test.ts +203 -0
package/src/selector/ExprProxy.ts +209 -0
package/src/selector/SelectorProxy.test.ts +172 -0
package/src/selector/SelectorProxy.ts +237 -0
package/src/selector/array.ts +37 -0
package/src/selector/boolean.ts +4 -0
package/src/selector/file.ts +14 -0
package/src/selector/i18n.ts +13 -0
package/src/selector/index.ts +159 -0
package/src/selector/number.ts +4 -0
package/src/selector/object.ts +22 -0
package/src/selector/primitive.ts +17 -0
package/src/selector/remote.ts +9 -0
package/src/selector/selector.test.ts +453 -0
package/src/selector/selectorOf.ts +7 -0
package/src/selector/string.ts +4 -0
package/src/source/file.ts +45 -0
package/src/source/i18n.ts +60 -0
package/src/source/index.ts +50 -0
package/src/source/remote.ts +54 -0
package/src/val/array.ts +10 -0
package/src/val/index.ts +90 -0
package/src/val/object.ts +13 -0
package/src/val/primitive.ts +8 -0

package/README.md CHANGED Viewed

@@ -54,14 +54,15 @@ Val is built on top of TypeScript and Git, letting you use types, branches, vers
 ## Installation
-- Make sure you have TypeScript 4.9+, Next 13+ (other meta frameworks will come), React 18+ (other frontend frameworks will come)
+- Make sure you have TypeScript 4.9+, Next 12+ (other meta frameworks will come), React 18+ (other frontend frameworks will come)
+- **NOTE**: THIS GUIDE is using the Next `/pages` directory NOT the new `/app` directory!
 - Install the packages:
 ```sh
 npm install @valbuild/core @valbuild/react @valbuild/server
 ```
-- Create your val.config.ts file:
+- Create your val.config.ts file. NOTE: this file should be in the same directory as `tsconfig.json`:
 ```ts
 // ./val.config.ts
@@ -83,7 +84,6 @@ export { s, val };
     ///...
     "strict": true,
     ///...
-    "jsx": "react-jsx",
     "jsxImportSource": "@valbuild/react"
     //...
   }
@@ -94,7 +94,7 @@ export { s, val };
 - Enable contextual editing: setup Val endpoints
 ```ts
-// ./pages/api/val/[...val].ts
+// ./src/pages/api/val/[...val].ts
 import { createRequestListener } from "@valbuild/server";
 import { NextApiHandler } from "next";
@@ -113,32 +113,23 @@ export const config = {
 };
 ```
-- Enable contextual editing: Use the Val provider in a top-level layout file:
+- Enable contextual editing: Use the Val provider in the \_app file:
 ```tsx
-// ./app/layout.tsx
+// ./src/pages/_app.tsx
 import { ValProvider } from "@valbuild/react";
-import "./globals.css";
+import type { AppProps } from "next/app";
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+function MyApp({ Component, pageProps }: AppProps) {
   return (
-    <html lang="en">
-      {/*
-        <head /> will contain the components returned by the nearest parent
-        head.tsx. Find out more at https://beta.nextjs.org/docs/api-reference/file-conventions/head
-      */}
-      <head />
-      <body>
-        <ValProvider host="/api/val">{children}</ValProvider>
-      </body>
-    </html>
+    <ValProvider host="/api/val">
+      <Component {...pageProps} />
+    </ValProvider>
   );
 }
+export default MyApp;
 ```
 ## Getting started
@@ -150,12 +141,12 @@ Content defined in Val is always defined `.val.{ts|js}` files.
 They must export a default `val.content` where the first argument equals the path of the file relative to the `val.config.{js|ts}` file.
 ```ts
-// ./app/example/blogs.val.ts
+// ./src/content/example/blogs.val.ts
-import { s, val } from "src/val.config";
+import { s, val } from "../../../val.config";
 export default val.content(
-  "/app/example/blogs", // <- NOTE: this must be the same path as the file
+  "/src/content/example/blogs", // <- NOTE: this must be the same path as the file
   s.array(s.object({ title: s.string(), text: s.string() })),
   [
     {
@@ -173,30 +164,27 @@ export default val.content(
 ### Use your content
 ```tsx
-// /app/example/page.tsx
+// ./src/pages/example/index.tsx
 import { NextPage } from "next";
 import { useVal } from "@valbuild/react";
-import blogsVal from "./blogs.val";
-import { val } from "val.config";
+import blogsVal from "@/content/example/blogs.val";
-const Home: NextPage = () => {
-  const blogs = useVal(blogsVal);
+const Blog: NextPage = () => {
+  const blog = useVal(blogsVal[0]);
   return (
     <main>
       <article>
-        {blogs.map((blog) => (
-          <section key={val.key(blog)}>
-            <h1>{blog.title}</h1>
-            <p>{blog.text}</p>
-          </section>
-        ))}
+        <section>
+          <h1>{blog.title}</h1>
+          <p>{blog.text}</p>
+        </section>
       </article>
     </main>
   );
 };
-export default Home;
+export default Blog;
 ```
 ## Concepts

package/jest.config.js ADDED Viewed

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

package/package.json CHANGED Viewed

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

package/src/Json.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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);
+  });
+  //
+});