@dxos/echo-react 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo-react",
-  "version": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
+  "version": "0.13.0",
   "description": "React integration for ECHO.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -25,8 +25,8 @@
     "src"
   ],
   "dependencies": {
-    "@effect/atom-react": "4.0.0-rc.108",
-    "@dxos/echo": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264"
+    "@effect/atom-react": "4.0.0",
+    "@dxos/echo": "0.13.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
@@ -34,7 +34,7 @@
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/echo-client": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264"
+    "@dxos/echo-client": "0.13.0"
   },
   "peerDependencies": {
     "react": "~19.2.7"

package/src/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-export * from './useQuery';
-export * from './usePagination';
-export * from './useType';
-export * from './useObject';
+export * from './useQuery.ts';
+export * from './usePagination.ts';
+export * from './useType.ts';
+export * from './useObject.ts';

package/src/useObject.test.tsx

@@ -4,7 +4,7 @@
 
 import { RegistryContext } from '@effect/atom-react/RegistryContext';
 import { renderHook, waitFor } from '@testing-library/react';
-import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
+import * as AtomRegistry from 'effect/reactivity/AtomRegistry';
 import React, { type PropsWithChildren } from 'react';
 import { describe, expect, test } from 'vitest';
 
@@ -12,7 +12,7 @@ import { Obj, Ref } from '@dxos/echo';
 import { createObject } from '@dxos/echo-client';
 import { TestSchema } from '@dxos/echo/testing';
 
-import { useObject } from './useObject';
+import { useObject } from './useObject.ts';
 
 const createWrapper = (registry: AtomRegistry.AtomRegistry) => {
   return ({ children }: PropsWithChildren) => (

package/src/useObject.ts

@@ -3,7 +3,7 @@
 //
 
 import { useAtomValue } from '@effect/atom-react/Hooks';
-import * as Atom from 'effect/unstable/reactivity/Atom';
+import * as Atom from 'effect/reactivity/Atom';
 import { useCallback, useMemo } from 'react';
 
 import { Obj, Ref } from '@dxos/echo';
@@ -46,6 +46,18 @@ export const useObject: {
    */
   <T extends Obj.Unknown>(ref: Ref.Ref<T> | undefined): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
 
+  /**
+   * Hook to subscribe to a Ref's target object, resolving a target that has been deleted.
+   *
+   * @param ref - The Ref to dereference and subscribe to
+   * @param options - `{ deleted: 'include' }` keeps a tombstoned target instead of reading it as undefined
+   * @returns The current target snapshot (or undefined if not loaded) and update callback
+   */
+  <T extends Obj.Unknown>(
+    ref: Ref.Ref<T> | undefined,
+    options: Ref.LoadOptions,
+  ): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
+
   /**
    * Hook to subscribe to an entire Echo object.
    * Returns a snapshot of the current object value and automatically re-renders when the object changes.
@@ -117,7 +129,13 @@ export const useObject: {
    * @returns The current property value (or undefined) and update callback
    */
   <T, K extends keyof T>(ref: Ref.Ref<T> | undefined, property: K): [T[K] | undefined, ObjectPropUpdateCallback<T[K]>];
-} = (<T extends Obj.Unknown, K extends keyof T>(objOrRef: T | Ref.Ref<T> | undefined, property?: K): any => {
+} = (<T extends Obj.Unknown, K extends keyof T>(
+  objOrRef: T | Ref.Ref<T> | undefined,
+  propertyOrOptions?: K | Ref.LoadOptions,
+): any => {
+  const isOptions = typeof propertyOrOptions === 'object' && propertyOrOptions !== null;
+  const property = isOptions ? undefined : propertyOrOptions;
+  const options = isOptions ? propertyOrOptions : undefined;
   const isRef = Ref.isRef(objOrRef);
   const liveObj = useResolveRef(objOrRef);
 
@@ -151,7 +169,7 @@ export const useObject: {
   if (property !== undefined) {
     return [useObjectProperty(liveObj, property), callback];
   } else {
-    return [useObjectValue(objOrRef), callback];
+    return [useObjectValue(objOrRef, options), callback];
   }
 }) as any;
 
@@ -160,19 +178,22 @@ export const useObject: {
  */
 export const useObjectValue = <T extends Obj.Unknown | Obj.Snapshot>(
   objOrRef: T | Ref.Ref<T> | undefined,
+  options?: Ref.LoadOptions,
 ): T extends Obj.Snapshot ? T : Obj.Snapshot<T & Obj.Unknown> | undefined => {
+  const deleted = options?.deleted;
   const atom = useMemo(() => {
     if (objOrRef == null) {
       return Atom.make<Obj.Snapshot<T & Obj.Unknown> | undefined>(() => undefined);
     }
     if (Ref.isRef(objOrRef)) {
-      return Obj.atom(objOrRef);
+      return Obj.atom(objOrRef, { deleted });
     }
     if (Obj.isSnapshot(objOrRef)) {
       return Atom.make<T>(() => objOrRef);
     }
     return Obj.atom(objOrRef as T & Obj.Unknown);
-  }, [objOrRef]);
+    // Keyed on the option's value: an inline options object is a new identity on every render.
+  }, [objOrRef, deleted]);
   return useAtomValue(atom as any);
 };
 

package/src/usePagination.test.tsx

@@ -9,7 +9,7 @@ import { Aggregate, Database, Feed, Filter, Obj, Order, Query } from '@dxos/echo
 import { EchoTestBuilder } from '@dxos/echo-client/testing';
 import { TestSchema } from '@dxos/echo/testing';
 
-import { usePagination } from './usePagination';
+import { usePagination } from './usePagination.ts';
 
 describe('usePagination', () => {
   let builder: EchoTestBuilder;

package/src/usePagination.ts

@@ -39,12 +39,8 @@ export type PaginationResult<T> = {
 /** Reactive snapshot handed to React by `useSyncExternalStore`; a fresh object only on real change. */
 type Snapshot<O> = { items: O[]; skip: number; limit: number; isLoading: boolean };
 
-/**
- * The element type a paginated query yields: the flat record for an aggregate query (branded with
- * {@link Query.AggregateResult}), otherwise the query's entity type. Mirrors `useQuery`'s overloads.
- */
 type PaginationElement<Q extends Query.Any> =
-  Query.Type<Q> extends Query.AggregateResult ? Query.Type<Q> : Entity.Entity<Query.Type<Q>>;
+  Query.Type<Q> extends Query.RecordResult ? Query.Type<Q> : Entity.Entity<Query.Type<Q>>;
 
 /**
  * Builds the external store backing `usePagination` for one query identity (filter/order/page

package/src/useQuery.test.tsx

@@ -9,7 +9,7 @@ import { Aggregate, Filter, Obj, Query } from '@dxos/echo';
 import { EchoTestBuilder } from '@dxos/echo-client/testing';
 import { TestSchema } from '@dxos/echo/testing';
 
-import { useQuery } from './useQuery';
+import { useQuery } from './useQuery.ts';
 
 describe('useQuery', () => {
   let builder: EchoTestBuilder;

package/src/useQuery.ts

@@ -11,9 +11,8 @@ const EMPTY_ARRAY: never[] = [];
 const noop = () => {};
 
 interface UseQueryFn {
-  // Aggregate queries produce flat records branded with `Query.AggregateResult`; return them as-is,
-  // never wrapped in `Entity.Entity` (they are not entities).
-  <R extends Query.AggregateResult>(resource: Database.Queryable | undefined, query: Query.Query<R>): R[];
+  <R extends Query.RecordResult>(resource: Database.Queryable | undefined, query: Query.Query<R>): R[];
+  <R extends Query.RecordResult>(resource: Database.Queryable | undefined, filter: Filter.Filter<R>): R[];
 
   <Q extends Query.Any, O extends Entity.Entity<Query.Type<Q>> = Entity.Entity<Query.Type<Q>>>(
     resource: Database.Queryable | undefined,
@@ -32,7 +31,7 @@ interface UseQueryFn {
  * @param queryOrFilter - The query or filter to apply. Query is memoized based on the AST. No need to call useMemo.
  */
 // The overloaded public signature returns `O[]` (entities) or the flat record `R[]` (aggregate
-// queries) depending on the query shape; the implementation forwards whatever the query result
+// rows and changes) depending on the query shape; the implementation forwards whatever the query result
 // produces, so — as with any implementation of a multi-signature overloaded function type — it is
 // typed as `any[]` here rather than picking one of the mutually-incompatible overload return shapes.
 export const useQuery: UseQueryFn = (