@dxos/echo 0.8.4-main.ead640a → 0.8.4-main.f466a3d56e

package/src/View.ts

@@ -0,0 +1,107 @@
+//
+// 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 { 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(
+  Type.object({
+    typename: 'org.dxos.type.view',
+    version: '0.1.0',
+  }),
+  internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--funnel--regular',
+    hue: 'green',
+  }),
+);
+
+export interface View extends Schema.Schema.Type<typeof ViewSchema> {}
+
+/**
+ * View instance type.
+ */
+// NOTE: This interface is explicitly defined rather than derived from the schema to avoid
+//   TypeScript "cannot be named" portability errors. The schema contains QueryAST.Query which
+//   references internal @dxos/echo-protocol module paths. Without this explicit interface,
+//   any schema using Ref.Ref(View) would inherit the non-portable type and fail to compile.
+// TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+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/hierarchy.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+
+describe('Hierarchy', () => {
+  test('setParent and getParent', async () => {
+    const parent = Obj.make(TestSchema.Organization, { name: 'parent' });
+    const child = Obj.make(TestSchema.Person, { name: 'child' });
+    expect(Obj.getParent(child)).toBeUndefined();
+
+    Obj.setParent(child, parent);
+    expect(Obj.getParent(child)).toBe(parent);
+
+    Obj.setParent(child, undefined);
+    expect(Obj.getParent(child)).toBeUndefined();
+  });
+
+  test('create object with Obj.Parent in props', () => {
+    const parent = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+    const child = Obj.make(TestSchema.Person, {
+      [Obj.Parent]: parent,
+      name: 'John',
+    });
+
+    expect(child.name).toBe('John');
+    expect(Obj.getParent(child)).toBe(parent);
+  });
+});

package/src/index.ts

@@ -2,15 +2,33 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './errors';
-export * from './query';
+export { QueryAST } from '@dxos/echo-protocol';
+// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.
+export { DXN } 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';
+export * as QueryResult from './QueryResult';
 export * as Ref from './Ref';
 export * as Relation from './Relation';
+export * as SchemaRegistry from './SchemaRegistry';
+export * as Tag from './Tag';
 export * as Type from './Type';
-
-export { QueryAST } from '@dxos/echo-protocol';
-export { DXN } from '@dxos/keys';
-export { type Live } from '@dxos/live-object';
+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,145 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { EchoObjectSchema } from '../Entity';
+import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } 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({
+    typename: 'org.dxos.type.test',
+    version: '0.1.0',
+  }),
+);
+
+type TestEchoSchema = Schema.Schema.Type<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: TestEchoSchema = {
+        id: 'test',
+        name: 'Primary Name',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestEchoSchema, obj)).toEqual('Primary Name');
+    });
+  });
+});