@dxos/effect 0.6.13-main.548ca8d → 0.6.14-main.1366248

package/src/ast.test.ts

@@ -0,0 +1,124 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { AST, Schema as S } from '@effect/schema';
+import { describe, test } from 'vitest';
+
+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('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.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 = findProperty(Contact, 'name' as JsonPath);
+      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 = findProperty(Contact, 'address.city' as JsonPath);
+      expect(prop).not.to.exist;
+    }
+  });
+
+  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.NonEmptyString,
+      emails: S.optional(S.mutable(S.Array(S.String))),
+      address: S.optional(
+        S.Struct({
+          zip: S.String,
+        }),
+      ),
+    });
+
+    const props: string[] = [];
+    visit(TestSchema.ast, (_, path) => props.push(path.join('.')));
+    console.log(JSON.stringify(props, null, 2));
+  });
+});

package/src/ast.ts

@@ -0,0 +1,253 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { AST, Schema as S } from '@effect/schema';
+import { Option, pipe } from 'effect';
+
+import { invariant } from '@dxos/invariant';
+
+//
+// Refs
+// https://effect.website/docs/guides/schema
+// https://www.npmjs.com/package/@effect/schema
+// https://effect-ts.github.io/effect/schema/AST.ts.html
+//
+
+export type SimpleType = 'object' | 'string' | 'number' | 'boolean' | 'enum' | 'literal';
+
+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 & { __JsonProp: true };
+export type JsonPath = string & { __JsonPath: true };
+
+const PATH_REGEX = /[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*/;
+const PROP_REGEX = /\w+/;
+
+/**
+ * https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html
+ */
+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>;
+
+/**
+ * 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,
+  /**
+   * Skip visiting children.
+   */
+  SKIP = 1,
+  /**
+   * Stop traversing immediately.
+   */
+  EXIT = 2,
+}
+
+export type Path = (string | number)[];
+
+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:
+ * - https://github.com/syntax-tree/unist-util-visit?tab=readme-ov-file#visitor
+ * - https://github.com/syntax-tree/unist-util-is?tab=readme-ov-file#test
+ */
+export const visit: {
+  (node: AST.AST, visitor: Visitor): void;
+  (node: AST.AST, test: Tester, visitor: Visitor): void;
+} = (node: AST.AST, testOrVisitor: Tester | Visitor, visitor?: Visitor): void => {
+  if (!visitor) {
+    visitNode(node, defaultTest, testOrVisitor);
+  } else {
+    visitNode(node, testOrVisitor as Tester, visitor);
+  }
+};
+
+const visitNode = (
+  node: AST.AST,
+  test: Tester | undefined,
+  visitor: Visitor,
+  path: Path = [],
+  depth = 0,
+): VisitResult | undefined => {
+  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;
+      }
+    }
+  }
+
+  // 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,7 +5,8 @@
 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';
 export * from './url';
-export * from './util';

package/src/url.ts

@@ -5,7 +5,7 @@
 import { AST, type Schema as S } from '@effect/schema';
 import { Option, pipe } from 'effect';
 
-import { decamelize } from './decamelize';
+import { decamelize } from '@dxos/util';
 
 const ParamKeyAnnotationId = Symbol.for('@dxos/schema/annotation/ParamKey');
 

package/dist/types/src/decamelize.d.ts

@@ -1,2 +0,0 @@
-export declare const decamelize: (str: string) => string;
-//# sourceMappingURL=decamelize.d.ts.map

package/dist/types/src/decamelize.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"decamelize.d.ts","sourceRoot":"","sources":["../../../src/decamelize.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,UAAU,QAAS,MAAM,WAmBrC,CAAC"}

package/dist/types/src/util.d.ts

@@ -1,3 +0,0 @@
-import { AST } from '@effect/schema';
-export declare const getAnnotation: <T>(annotationId: symbol) => (annotated: AST.Annotated) => T | undefined;
-//# sourceMappingURL=util.d.ts.map

package/dist/types/src/util.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../src/util.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAGrC,eAAO,MAAM,aAAa,GACvB,CAAC,gBAAgB,MAAM,iBACZ,GAAG,CAAC,SAAS,KAAG,CAAC,GAAG,SAC4C,CAAC"}

package/src/decamelize.ts

@@ -1,36 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-const LOW_DASH = '_'.codePointAt(0)!;
-const SMALL_A = 'a'.codePointAt(0)!;
-const CAPITAL_A = 'A'.codePointAt(0)!;
-const SMALL_Z = 'z'.codePointAt(0)!;
-const CAPITAL_Z = 'Z'.codePointAt(0)!;
-
-const isLower = (char: number) => char >= SMALL_A && char <= SMALL_Z;
-
-const isUpper = (char: number) => char >= CAPITAL_A && char <= CAPITAL_Z;
-
-const toLower = (char: number) => char + 0x20;
-
-export const decamelize = (str: string) => {
-  const firstChar = str.charCodeAt(0);
-  if (!isLower(firstChar)) {
-    return str;
-  }
-  const length = str.length;
-  let changed = false;
-  const out: number[] = [];
-  for (let i = 0; i < length; ++i) {
-    const c = str.charCodeAt(i);
-    if (isUpper(c)) {
-      out.push(LOW_DASH);
-      out.push(toLower(c));
-      changed = true;
-    } else {
-      out.push(c);
-    }
-  }
-  return changed ? String.fromCharCode.apply(undefined, out) : str;
-};

package/src/util.ts

@@ -1,11 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { AST } from '@effect/schema';
-import { Option, pipe } from 'effect';
-
-export const getAnnotation =
-  <T>(annotationId: symbol) =>
-  (annotated: AST.Annotated): T | undefined =>
-    pipe(AST.getAnnotation<T>(annotationId)(annotated), Option.getOrUndefined);