@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/View.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { QueryAST } from '@dxos/echo-protocol';
+import { JsonPath } from '@dxos/effect';
+import { DXN, PublicKey } from '@dxos/keys';
+
+import * as Annotation from './Annotation';
+import * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import * as Query from './Query';
+import * as Type from './Type';
+
+/**
+ * Stored field metadata (e.g., for UX).
+ */
+export const FieldSchema = Schema.Struct({
+  id: Schema.String,
+  path: JsonPath,
+  visible: Schema.optional(Schema.Boolean),
+
+  // TODO(wittjosiah): Presentation-specific?
+  referencePath: Schema.optional(JsonPath),
+});
+
+export type FieldType = Schema.Schema.Type<typeof FieldSchema>;
+
+export const KeyValueProps = Schema.Record({ key: Schema.String, value: Schema.Any });
+
+export const createFieldId = () => PublicKey.random().truncate();
+
+export const Projection = Schema.Struct({
+  /**
+   * Optional schema override used to customize the underlying schema.
+   */
+  schema: internal.JsonSchemaType.pipe(Schema.optional),
+
+  /**
+   * UX metadata associated with displayed fields (in table, form, etc.)
+   */
+  // TODO(wittjosiah): Should this just be an array of JsonPath?
+  fields: Schema.Array(FieldSchema),
+
+  /**
+   * The id for the field used to pivot the view.
+   * E.g., the field to use for kanban columns or the field to use for map coordinates.
+   */
+  pivotFieldId: Schema.String.pipe(Schema.optional),
+});
+
+export type Projection = Schema.Schema.Type<typeof Projection>;
+
+/**
+ * Views are generated or user-defined projections of a schema's properties.
+ * They are used to configure the visual representation of the data.
+ */
+const ViewSchema = Schema.Struct({
+  /**
+   * Query used to retrieve data.
+   * Can be a user-provided query grammar string or a query AST.
+   */
+  query: Schema.Struct({
+    raw: Schema.optional(Schema.String),
+    ast: QueryAST.Query,
+  }),
+
+  /**
+   * Projection of the data returned from the query.
+   */
+  projection: Projection,
+}).pipe(
+  internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--funnel--regular',
+    hue: 'green',
+  }),
+  Type.makeObject(DXN.make('org.dxos.type.view', '0.1.0')),
+);
+
+// NOTE: Declared as a named interface and the `View` const is annotated `Type.Obj<View>` so
+//   downstream consumers see a named `View` type instead of the inlined `QueryAST.Query` union.
+//   Without the named interface, embedding `Type.getSchema(View.View)` in a downstream
+//   `Schema.Struct` triggers TS2742 portability errors (e.g. plugin-kanban, plugin-table).
+// TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+export interface View extends Type.InstanceType<typeof ViewSchema> {}
+
+export const View: Type.Obj<View> = ViewSchema as any;
+
+export const make = (props: Partial<Obj.MakeProps<typeof View>>): View => {
+  return Obj.make(View, {
+    query: { ast: Query.select(Filter.nothing()).ast },
+    projection: { fields: [] },
+    ...props,
+  });
+};

package/src/exemplars.test.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+import type * as Type from './Type';
+
+describe('Exemplars', () => {
+  test('factory', ({ expect }) => {
+    const factory = <S extends Type.AnyObj>(schema: S) => {
+      return (props: Obj.MakeProps<S>) => Obj.make(schema, props);
+    };
+
+    const makePerson = factory(TestSchema.Person);
+    const person = makePerson({ name: 'John Doe' });
+    expect(person.name).toBe('John Doe');
+  });
+});

package/src/index.ts

@@ -3,18 +3,21 @@
 //
 
 export { QueryAST } from '@dxos/echo-protocol';
-// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.
-export { DXN } from '@dxos/keys';
+export { DXN, EchoURI, URI } from '@dxos/keys';
 
 export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
+// TODO(burdon): Rename to Error (less problematic than Obj/Object).
 export * as Err from './Err';
+export * as Feed from './Feed';
 export * as Filter from './Filter';
 export * as Format from './Format';
 export * as Hypergraph from './Hypergraph';
+export * as Json from './Json';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
+export * as Migration from './Migration';
 export * as Obj from './Obj';
 export * as Order from './Order';
 export * as Query from './Query';
@@ -24,3 +27,7 @@ export * as Relation from './Relation';
 export * as SchemaRegistry from './SchemaRegistry';
 export * as Tag from './Tag';
 export * as Type from './Type';
+export * as Collection from './Collection';
+export * as View from './View';
+export * as Dataset from './Dataset';
+export * as Extension from './Extension';

package/src/internal/Annotation/annotations.test.ts

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import { createEchoSchema } from '../../testing';
+import * as Type from '../../Type';
+import { EntityKind } from '../common/types';
+import { EchoObjectSchema } from '../Entity';
+import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema, getTypeAnnotation } from './annotations';
+
+// TODO(dmaretskyi): Use one of the testing schemas.
+const TestObject = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  fallbackName: Schema.optional(Schema.String),
+  other: Schema.String,
+}).pipe(LabelAnnotation.set(['name', 'fallbackName']));
+
+type TestObject = Schema.Schema.Type<typeof TestObject>;
+
+const TestEchoSchema = TestObject.pipe(EchoObjectSchema(DXN.make('org.dxos.type.test', '0.1.0')));
+
+type TestEchoSchema = Type.InstanceType<typeof TestEchoSchema>;
+
+describe('annotations', () => {
+  describe('Typename', () => {
+    test('should validate typename', ({ expect }) => {
+      // Valid (reverse-DNS format).
+      expect(TypenameSchema.make('org.dxos.type.foo')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.fooBar')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.foobar')).to.exist;
+
+      // Invalid.
+      expect(() => TypenameSchema.make('dxn:dxos.org')).to.throw();
+      expect(() => TypenameSchema.make('2dxos.org')).to.throw();
+      expect(() => TypenameSchema.make('dxos org')).to.throw();
+    });
+
+    test('should validate version', ({ expect }) => {
+      // Valid.
+      expect(VersionSchema.make('0.1.0')).to.exist;
+
+      // Invalid.
+      expect(() => VersionSchema.make('0.1.x')).to.throw();
+      expect(() => VersionSchema.make('0.1.0-alpha')).to.throw();
+    });
+  });
+
+  describe('getLabelWithSchema', () => {
+    test('should return first available label value', ({ expect }) => {
+      const obj: TestObject = {
+        name: 'Primary Name',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Primary Name');
+    });
+
+    test('should fallback to second path if first is undefined', ({ expect }) => {
+      const obj: TestObject = {
+        name: undefined,
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should return undefined if no label paths resolve', ({ expect }) => {
+      const obj: TestObject = {
+        name: undefined,
+        fallbackName: undefined,
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should skip empty string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should skip whitespace-only string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '   ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should return undefined if all paths are empty strings', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: '',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should return undefined if all paths are whitespace-only', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  ',
+        fallbackName: '\t\n',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should preserve original string with leading/trailing whitespace when valid', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  Valid Name  ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('  Valid Name  ');
+    });
+
+    test('should return label from echo object', ({ expect }) => {
+      const obj = {
+        id: 'test',
+        name: 'Primary Name',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      } as unknown as TestEchoSchema;
+
+      expect(getLabelWithSchema(Type.getSchema(TestEchoSchema), obj)).toEqual('Primary Name');
+    });
+  });
+
+  // `getTypeAnnotation` reads annotations from an Effect Schema. To read off a
+  // `Type.Type` entity (static or persisted), unwrap with `Type.getSchema(entity)`
+  // first — that handles both the static `StaticTypeSchemaSlot` case and the
+  // persisted `jsonSchema` rebuild case.
+  describe('getTypeAnnotation via Type.getSchema(entity)', () => {
+    test('returns TypeAnnotation for a static Type.Obj entity', ({ expect }) => {
+      const annotation = getTypeAnnotation(Type.getSchema(TestEchoSchema));
+      expect(annotation).toBeDefined();
+      expect(annotation?.kind).toBe(EntityKind.Object);
+      expect(annotation?.typename).toBe('org.dxos.type.test');
+    });
+
+    test('returns TypeAnnotation for a persisted Type.Type entity', ({ expect }) => {
+      const persisted = createEchoSchema(Type.getSchema(TestEchoSchema));
+      const annotation = getTypeAnnotation(Type.getSchema(persisted));
+      expect(annotation).toBeDefined();
+      expect(annotation?.typename).toBe('org.dxos.type.test');
+    });
+  });
+});