@dxos/effect 0.6.14-main.f49f251 → 0.6.14-staging.3e2eaca

package/src/ast.test.ts

@@ -2,38 +2,114 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema as S } from '@effect/schema';
-import { describe, expect, test } from 'vitest';
+import { AST, Schema as S } from '@effect/schema';
+import { describe, test } from 'vitest';
 
-import { getProperty, isLeafType, visit } from './ast';
+import { invariant } from '@dxos/invariant';
+
+import {
+  findAnnotation,
+  findNode,
+  findProperty,
+  getAnnotation,
+  getSimpleType,
+  isSimpleType,
+  visit,
+  type JsonPath,
+  type JsonProp,
+} from './ast';
+
+const ZipCode = S.String.pipe(
+  S.pattern(/^\d{5}$/, {
+    typeId: Symbol.for('@example/schema/ZipCode'),
+    identifier: 'ZipCode',
+    title: 'ZIP code',
+    description: 'Simple 5 digit zip code',
+  }),
+);
+
+const LatLng = S.Struct({
+  lat: S.Number,
+  lng: S.Number,
+});
+
+const Contact = S.Struct({
+  name: S.String,
+  address: S.Struct({
+    zip: ZipCode,
+    location: S.optional(LatLng),
+  }),
+});
+
+const getTitle = getAnnotation(AST.TitleAnnotationId);
 
 describe('AST', () => {
-  test('getProperty', () => {
+  test('validation', ({ expect }) => {
+    const validate = S.validateSync(ZipCode);
+    validate('11205');
+
+    expect(() => validate(null)).to.throw();
+    expect(() => validate(12345)).to.throw();
+    expect(() => validate('')).to.throw();
+    expect(() => validate('1234')).to.throw();
+  });
+
+  test('findNode', ({ expect }) => {
     const TestSchema = S.Struct({
-      name: S.String,
-      address: S.Struct({
-        zip: S.String,
-      }),
-    });
+      name: S.optional(S.String),
+    }).pipe(S.mutable);
+
+    const prop = findProperty(TestSchema, 'name' as JsonProp);
+    invariant(prop);
+    const node = findNode(prop, isSimpleType);
+    invariant(node);
+    const type = getSimpleType(node);
+    expect(type).to.eq('string');
+  });
 
+  test('findProperty', ({ expect }) => {
     {
-      const prop = getProperty(TestSchema, 'name');
+      const prop = findProperty(Contact, 'name' as JsonPath);
       expect(prop).to.exist;
     }
     {
-      const prop = getProperty(TestSchema, 'address.zip');
-      expect(prop).to.exist;
+      const prop = findProperty(Contact, 'address.zip' as JsonPath);
+      invariant(prop);
+      expect(getTitle(prop)).to.eq('ZIP code');
+    }
+    {
+      const prop = findProperty(Contact, 'address.location.lat' as JsonPath);
+      invariant(prop);
+      expect(AST.isNumberKeyword(prop)).to.be.true;
     }
     {
-      const prop = getProperty(TestSchema, 'address.city');
+      const prop = findProperty(Contact, 'address.city' as JsonPath);
       expect(prop).not.to.exist;
     }
   });
 
-  test('visit', () => {
+  test('findAnnotation', ({ expect }) => {
+    const Type = S.NonEmptyString.pipe(S.pattern(/^\d{5}$/)).annotations({
+      [AST.TitleAnnotationId]: 'original title',
+    });
+    const Contact = S.Struct({
+      p1: Type.annotations({ [AST.TitleAnnotationId]: 'new title' }),
+      p2: Type.annotations({ [AST.TitleAnnotationId]: 'new title' }).pipe(S.optional),
+      p3: S.optional(Type.annotations({ [AST.TitleAnnotationId]: 'new title' })),
+    });
+
+    {
+      const prop = findProperty(Contact, 'p3' as JsonPath);
+      invariant(prop);
+      const value = findAnnotation(prop, AST.TitleAnnotationId);
+      expect(value).to.eq('new title');
+    }
+  });
+
+  test('visit', ({ expect }) => {
     const TestSchema = S.Struct({
-      name: S.optional(S.String),
-      emails: S.mutable(S.Array(S.String)),
+      name: S.NonEmptyString,
+      emails: S.optional(S.mutable(S.Array(S.String))),
       address: S.optional(
         S.Struct({
           zip: S.String,
@@ -42,11 +118,7 @@ describe('AST', () => {
     });
 
     const props: string[] = [];
-    visit(TestSchema.ast, (node, path) => {
-      if (isLeafType(node)) {
-        props.push(path.join('.'));
-      }
-    });
-    expect(props).to.deep.eq(['name', 'address.zip']);
+    visit(TestSchema.ast, (_, path) => props.push(path.join('.')));
+    console.log(JSON.stringify(props, null, 2));
   });
 });

package/src/ast.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { AST, type Schema as S } from '@effect/schema';
+import { AST, Schema as S } from '@effect/schema';
 import { Option, pipe } from 'effect';
 
 import { invariant } from '@dxos/invariant';
@@ -14,47 +14,54 @@ import { invariant } from '@dxos/invariant';
 // https://effect-ts.github.io/effect/schema/AST.ts.html
 //
 
-export const isLeafType = (node: AST.AST) => !AST.isTupleType(node) && !AST.isTypeLiteral(node);
+export type SimpleType = 'object' | 'string' | 'number' | 'boolean' | 'enum' | 'literal';
 
-/**
- * Get annotation or return undefined.
- */
-export const getAnnotation = <T>(annotationId: symbol, node: AST.Annotated): T | undefined =>
-  pipe(AST.getAnnotation<T>(annotationId)(node), Option.getOrUndefined);
-
-/**
- * Get type node.
- */
-export const getType = (node: AST.AST): AST.AST | undefined => {
-  if (AST.isUnion(node)) {
-    return node.types.find((type) => getType(type));
-  } else if (AST.isRefinement(node)) {
-    return getType(node.from);
-  } else {
-    return node;
+export const getSimpleType = (node: AST.AST): SimpleType | undefined => {
+  if (AST.isObjectKeyword(node)) {
+    return 'object';
+  }
+  if (AST.isStringKeyword(node)) {
+    return 'string';
+  }
+  if (AST.isNumberKeyword(node)) {
+    return 'number';
+  }
+  if (AST.isBooleanKeyword(node)) {
+    return 'boolean';
+  }
+  if (AST.isEnums(node)) {
+    return 'enum';
+  }
+  if (AST.isLiteral(node)) {
+    return 'literal';
   }
 };
 
+export const isSimpleType = (node: AST.AST) => !!getSimpleType(node);
+
+//
+// Branded types
+//
+
+export type JsonProp = string & { __JsonPath: true; __JsonProp: true };
+export type JsonPath = string & { __JsonPath: true };
+
+const PATH_REGEX = /[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*/;
+const PROP_REGEX = /\w+/;
+
 /**
- * Get the AST node for the given property (dot-path).
+ * https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html
  */
-export const getProperty = (schema: S.Schema<any>, path: string): AST.AST | undefined => {
-  let node: AST.AST = schema.ast;
-  for (const part of path.split('.')) {
-    const props = AST.getPropertySignatures(node);
-    const prop = props.find((prop) => prop.name === part);
-    if (!prop) {
-      return undefined;
-    }
-
-    // TODO(burdon): Check if leaf.
-    const type = getType(prop.type);
-    invariant(type, `invalid type: ${path}`);
-    node = type;
-  }
+export const JsonPath = S.NonEmptyString.pipe(S.pattern(PATH_REGEX)) as any as S.Schema<JsonPath>;
+export const JsonProp = S.NonEmptyString.pipe(S.pattern(PROP_REGEX)) as any as S.Schema<JsonProp>;
 
-  return node;
-};
+/**
+ * Get annotation or return undefined.
+ */
+export const getAnnotation =
+  <T>(annotationId: symbol) =>
+  (node: AST.Annotated): T | undefined =>
+    pipe(AST.getAnnotation<T>(annotationId)(node), Option.getOrUndefined);
 
 export enum VisitResult {
   CONTINUE = 0,
@@ -63,16 +70,18 @@ export enum VisitResult {
    */
   SKIP = 1,
   /**
-   * Stop traversing immeditaely.
+   * Stop traversing immediately.
    */
   EXIT = 2,
 }
 
 export type Path = (string | number)[];
 
-export type Tester = (node: AST.AST, path: Path, depth: number) => VisitResult;
+export type Tester = (node: AST.AST, path: Path, depth: number) => VisitResult | undefined;
 export type Visitor = (node: AST.AST, path: Path, depth: number) => void;
 
+const defaultTest: Tester = (node) => (isSimpleType(node) ? VisitResult.CONTINUE : VisitResult.SKIP);
+
 /**
  * Visit leaf nodes.
  * Refs:
@@ -84,7 +93,7 @@ export const visit: {
   (node: AST.AST, test: Tester, visitor: Visitor): void;
 } = (node: AST.AST, testOrVisitor: Tester | Visitor, visitor?: Visitor): void => {
   if (!visitor) {
-    visitNode(node, undefined, testOrVisitor);
+    visitNode(node, defaultTest, testOrVisitor);
   } else {
     visitNode(node, testOrVisitor as Tester, visitor);
   }
@@ -97,29 +106,148 @@ const visitNode = (
   path: Path = [],
   depth = 0,
 ): VisitResult | undefined => {
-  for (const prop of AST.getPropertySignatures(node)) {
-    const currentPath = [...path, prop.name.toString()];
-    const type = getType(prop.type);
-    if (type) {
-      const result = test?.(node, path, depth) ?? VisitResult.CONTINUE;
+  const result = test?.(node, path, depth) ?? VisitResult.CONTINUE;
+  if (result === VisitResult.EXIT) {
+    return result;
+  }
+  if (result !== VisitResult.SKIP) {
+    visitor(node, path, depth);
+  }
+
+  // Object.
+  if (AST.isTypeLiteral(node)) {
+    for (const prop of AST.getPropertySignatures(node)) {
+      const currentPath = [...path, prop.name.toString()];
+      const result = visitNode(prop.type, test, visitor, currentPath, depth + 1);
+      if (result === VisitResult.EXIT) {
+        return result;
+      }
+    }
+  }
+
+  // Array.
+  else if (AST.isTupleType(node)) {
+    for (const [i, element] of node.elements.entries()) {
+      const currentPath = [...path, i];
+      const result = visitNode(element.type, test, visitor, currentPath, depth);
       if (result === VisitResult.EXIT) {
         return result;
       }
+    }
+  }
 
-      visitor(type, currentPath, depth);
-
-      if (result !== VisitResult.SKIP) {
-        if (AST.isTypeLiteral(type)) {
-          visitNode(type, test, visitor, currentPath, depth + 1);
-        } else if (AST.isTupleType(type)) {
-          for (const [i, elementType] of type.elements.entries()) {
-            const type = getType(elementType.type);
-            if (type) {
-              visitNode(type, test, visitor, [i, ...currentPath], depth);
-            }
-          }
-        }
+  // Branching union.
+  else if (AST.isUnion(node)) {
+    for (const type of node.types) {
+      const result = visitNode(type, test, visitor, path, depth);
+      if (result === VisitResult.EXIT) {
+        return result;
       }
     }
   }
+
+  // Refinement.
+  else if (AST.isRefinement(node)) {
+    const result = visitNode(node.from, test, visitor, path, depth);
+    if (result === VisitResult.EXIT) {
+      return result;
+    }
+  }
+
+  // TODO(burdon): Transform?
+};
+
+/**
+ * Recursively descend into AST to find first node that passes the test.
+ */
+// TODO(burdon): Reuse visitor.
+export const findNode = (node: AST.AST, test: (node: AST.AST) => boolean): AST.AST | undefined => {
+  if (test(node)) {
+    return node;
+  }
+
+  // Object.
+  else if (AST.isTypeLiteral(node)) {
+    for (const prop of AST.getPropertySignatures(node)) {
+      const child = findNode(prop.type, test);
+      if (child) {
+        return child;
+      }
+    }
+  }
+
+  // Array.
+  else if (AST.isTupleType(node)) {
+    for (const [_, element] of node.elements.entries()) {
+      const child = findNode(element.type, test);
+      if (child) {
+        return child;
+      }
+    }
+  }
+
+  // Branching union.
+  else if (AST.isUnion(node)) {
+    for (const type of node.types) {
+      const child = findNode(type, test);
+      if (child) {
+        return child;
+      }
+    }
+  }
+
+  // Refinement.
+  else if (AST.isRefinement(node)) {
+    return findNode(node.from, test);
+  }
+
+  return undefined;
+};
+
+/**
+ * Get the AST node for the given property (dot-path).
+ */
+export const findProperty = (schema: S.Schema<any>, path: JsonPath | JsonProp): AST.AST | undefined => {
+  const getProp = (node: AST.AST, path: JsonProp[]): AST.AST | undefined => {
+    const [name, ...rest] = path;
+    const typeNode = findNode(node, AST.isTypeLiteral);
+    invariant(typeNode);
+    for (const prop of AST.getPropertySignatures(typeNode)) {
+      if (prop.name === name) {
+        if (rest.length) {
+          return getProp(prop.type, rest);
+        } else {
+          return prop.type;
+        }
+      }
+    }
+
+    return undefined;
+  };
+
+  return getProp(schema.ast, path.split('.') as JsonProp[]);
+};
+
+/**
+ * Recursively descend into AST to find first matching annotations
+ */
+export const findAnnotation = <T>(node: AST.AST, annotationId: symbol): T | undefined => {
+  const getAnnotationById = getAnnotation(annotationId);
+  const getBaseAnnotation = (node: AST.AST): T | undefined => {
+    const value = getAnnotationById(node);
+    if (value !== undefined) {
+      return value as T;
+    }
+
+    if (AST.isUnion(node)) {
+      for (const type of node.types) {
+        const value = getBaseAnnotation(type);
+        if (value !== undefined) {
+          return value as T;
+        }
+      }
+    }
+  };
+
+  return getBaseAnnotation(node);
 };

package/src/index.ts

@@ -5,6 +5,7 @@
 import { AST, JSONSchema, Schema as S } from '@effect/schema';
 import type * as Types from 'effect/Types';
 
+// TODO(dmaretskyi): Remove re-exports.
 export { AST, JSONSchema, S, Types };
 
 export * from './ast';