@dxos/effect 0.6.14-staging.e15392e → 0.7.1-staging.599df14

package/src/ast.test.ts

@@ -2,38 +2,136 @@
 // 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,
+  getDiscriminatingProps,
+  getDiscriminatedType,
+  getSimpleType,
+  isOption,
+  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 = getProperty(TestSchema, 'address.city');
+      const prop = findProperty(Contact, 'address.location.lat' as JsonPath);
+      invariant(prop);
+      expect(AST.isNumberKeyword(prop)).to.be.true;
+    }
+    {
+      const prop = findProperty(Contact, 'address.city' as JsonPath);
       expect(prop).not.to.exist;
     }
   });
 
-  test('visit', () => {
+  test('findAnnotation', ({ expect }) => {
+    const TestSchema = S.NonEmptyString.pipe(S.pattern(/^\d{5}$/)).annotations({
+      [AST.TitleAnnotationId]: 'original title',
+    });
+
+    const ContactSchema = S.Struct({
+      p1: TestSchema.annotations({ [AST.TitleAnnotationId]: 'new title' }),
+      p2: TestSchema.annotations({ [AST.TitleAnnotationId]: 'new title' }).pipe(S.optional),
+      p3: S.optional(TestSchema.annotations({ [AST.TitleAnnotationId]: 'new title' })),
+    });
+
+    for (const p of ['p1', 'p2', 'p3']) {
+      const prop = findProperty(ContactSchema, p as JsonPath);
+      invariant(prop);
+      const value = findAnnotation(prop, AST.TitleAnnotationId);
+      expect(value, `invalid title for ${p}`).to.eq('new title');
+    }
+  });
+
+  test('findAnnotation skips defaults', ({ expect }) => {
+    const annotation = findAnnotation(
+      S.String.annotations({ [AST.TitleAnnotationId]: 'test' }).ast,
+      AST.TitleAnnotationId,
+      { noDefault: true },
+    );
+    expect(annotation).to.eq('test');
+
+    const annotationIds = [AST.TitleAnnotationId, AST.DescriptionAnnotationId];
+    const schemas = [S.Object, S.String, S.Number, S.Boolean];
+    for (const schema of schemas) {
+      for (const annotationId of annotationIds) {
+        const annotation = findAnnotation(schema.ast, annotationId, { noDefault: true });
+        expect(annotation, schema.ast._tag).to.eq(undefined);
+      }
+    }
+  });
+
+  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 +140,47 @@ 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('.')));
+  });
+
+  test('discriminated unions', ({ expect }) => {
+    const TestUnionSchema = S.Union(
+      S.Struct({ kind: S.Literal('a'), label: S.String }),
+      S.Struct({ kind: S.Literal('b'), count: S.Number, active: S.Boolean }),
+    );
+
+    type TestUnionType = S.Schema.Type<typeof TestUnionSchema>;
+
+    {
+      expect(isOption(TestUnionSchema.ast)).to.be.false;
+      expect(getDiscriminatingProps(TestUnionSchema.ast)).to.deep.eq(['kind']);
+
+      const node = findNode(TestUnionSchema.ast, isSimpleType);
+      expect(node).to.eq(TestUnionSchema.ast);
+    }
+
+    {
+      invariant(AST.isUnion(TestUnionSchema.ast));
+      const [a, b] = TestUnionSchema.ast.types;
+
+      const obj1: TestUnionType = {
+        kind: 'a',
+        label: 'test',
+      };
+
+      const obj2: TestUnionType = {
+        kind: 'b',
+        count: 100,
+        active: true,
+      };
+
+      expect(getDiscriminatedType(TestUnionSchema.ast, obj1)?.toJSON()).to.deep.eq(a.toJSON());
+      expect(getDiscriminatedType(TestUnionSchema.ast, obj2)?.toJSON()).to.deep.eq(b.toJSON());
+      expect(getDiscriminatedType(TestUnionSchema.ast)?.toJSON()).to.deep.eq(
+        S.Struct({
+          kind: S.Literal('a', 'b'),
+        }).ast.toJSON(),
+      );
+    }
   });
 });

package/src/ast.ts

@@ -2,59 +2,73 @@
 // 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';
+import { nonNullable } from '@dxos/util';
 
 //
 // Refs
-// https://effect.website/docs/guides/schema
+// https://effect.website/docs/schema/introduction
 // https://www.npmjs.com/package/@effect/schema
 // 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.
+ * Get the base type; e.g., traverse through refinements.
  */
-export const getAnnotation = <T>(annotationId: symbol, node: AST.Annotated): T | undefined =>
-  pipe(AST.getAnnotation<T>(annotationId)(node), Option.getOrUndefined);
+export const getSimpleType = (node: AST.AST): SimpleType | undefined => {
+  if (AST.isObjectKeyword(node) || AST.isTypeLiteral(node) || isDiscriminatedUnion(node)) {
+    return 'object';
+  }
 
-/**
- * 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;
+  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): boolean => !!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;
-    }
+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>;
 
-    // TODO(burdon): Check if leaf.
-    const type = getType(prop.type);
-    invariant(type, `invalid type: ${path}`);
-    node = type;
-  }
-
-  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 +77,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 +100,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 +113,258 @@ 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;
       }
+    }
+  }
 
-      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);
-            }
-          }
+  // 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;
+      }
+    }
+  }
+
+  // Branching union (e.g., optional, discriminated unions).
+  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): Transforms?
+};
+
+/**
+ * Recursively descend into AST to find first node that passes the test.
+ */
+// TODO(burdon): Rewrite using visitNode?
+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;
+      }
+    }
+  }
+
+  // Tuple.
+  else if (AST.isTupleType(node)) {
+    for (const [_, element] of node.elements.entries()) {
+      const child = findNode(element.type, test);
+      if (child) {
+        return child;
+      }
+    }
+  }
+
+  // Branching union (e.g., optional, discriminated unions).
+  else if (AST.isUnion(node)) {
+    if (isOption(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);
+  }
+};
+
+/**
+ * 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 getProp(schema.ast, path.split('.') as JsonProp[]);
+};
+
+//
+// Annotations
+//
+
+const defaultAnnotations: Record<string, AST.Annotated> = {
+  ['ObjectKeyword' as const]: AST.objectKeyword,
+  ['StringKeyword' as const]: AST.stringKeyword,
+  ['NumberKeyword' as const]: AST.numberKeyword,
+  ['BooleanKeyword' as const]: AST.booleanKeyword,
+};
+
+/**
+ * Recursively descend into AST to find first matching annotations.
+ * Optionally skips default annotations for basic types (e.g., 'a string').
+ */
+export const findAnnotation = <T>(
+  node: AST.AST,
+  annotationId: symbol,
+  options?: { noDefault: boolean },
+): T | undefined => {
+  const getAnnotationById = getAnnotation(annotationId);
+
+  const getBaseAnnotation = (node: AST.AST): T | undefined => {
+    const value = getAnnotationById(node);
+    if (value !== undefined) {
+      if (options?.noDefault && value === defaultAnnotations[node._tag]?.annotations[annotationId]) {
+        return undefined;
+      }
+
+      return value as T;
+    }
+
+    if (AST.isUnion(node)) {
+      if (isOption(node)) {
+        return getAnnotationById(node.types[0]) as T;
+      }
+    }
+  };
+
+  return getBaseAnnotation(node);
+};
+
+//
+// Unions
+//
+
+/**
+ * Effect S.optional creates a union type with undefined as the second type.
+ */
+export const isOption = (node: AST.AST): boolean => {
+  return AST.isUnion(node) && node.types.length === 2 && AST.isUndefinedKeyword(node.types[1]);
+};
+
+/**
+ * Determines if the node is a union of literal types.
+ */
+export const isLiteralUnion = (node: AST.AST): boolean => {
+  return AST.isUnion(node) && node.types.every(AST.isLiteral);
+};
+
+/**
+ * Determines if the node is a discriminated union.
+ */
+export const isDiscriminatedUnion = (node: AST.AST): boolean => {
+  return AST.isUnion(node) && !!getDiscriminatingProps(node)?.length;
+};
+
+/**
+ * Get the discriminating properties for the given union type.
+ */
+export const getDiscriminatingProps = (node: AST.AST): string[] | undefined => {
+  invariant(AST.isUnion(node));
+  if (isOption(node)) {
+    return;
+  }
+
+  // Get common literals across all types.
+  return node.types.reduce<string[]>((shared, type) => {
+    const props = AST.getPropertySignatures(type)
+      // TODO(burdon): Should check each literal is unique.
+      .filter((p) => AST.isLiteral(p.type))
+      .map((p) => p.name.toString());
+
+    // Return common literals.
+    return shared.length === 0 ? props : shared.filter((prop) => props.includes(prop));
+  }, []);
+};
+
+/**
+ * Get the discriminated type for the given value.
+ */
+export const getDiscriminatedType = (node: AST.AST, value: Record<string, any> = {}): AST.AST | undefined => {
+  invariant(AST.isUnion(node));
+  invariant(value);
+  const props = getDiscriminatingProps(node);
+  if (!props?.length) {
+    return;
+  }
+
+  // Match provided values.
+  for (const type of node.types) {
+    const match = AST.getPropertySignatures(type)
+      .filter((prop) => props?.includes(prop.name.toString()))
+      .every((prop) => {
+        invariant(AST.isLiteral(prop.type));
+        return prop.type.literal === value[prop.name.toString()];
+      });
+
+    if (match) {
+      return type;
+    }
+  }
+
+  // Create union of discriminating properties.
+  // NOTE: This may not work with non-overlapping variants.
+  // TODO(burdon): Iterate through props and knock-out variants that don't match.
+  const fields = Object.fromEntries(
+    props
+      .map((prop) => {
+        const literals = node.types
+          .map((type) => {
+            const literal = AST.getPropertySignatures(type).find((p) => p.name.toString() === prop)!;
+            invariant(AST.isLiteral(literal.type));
+            return literal.type.literal;
+          })
+          .filter(nonNullable);
+
+        return literals.length ? [prop, S.Literal(...literals)] : undefined;
+      })
+      .filter(nonNullable),
+  );
+
+  const schema = S.Struct(fields);
+  return schema.ast;
 };

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';