@dxos/echo-query 0.9.0 → 0.9.1-main.c7dcc2e112

package/dist/query-lite/index.d.ts

@@ -8785,27 +8785,8 @@ type MaybePromise<T$1> = T$1 | Promise<T$1>;
  */
 type ToMutable<T$1> = T$1 extends object ? { -readonly [K in keyof T$1]: T$1[K] extends readonly (infer U)[] ? U[] : T$1[K] } : T$1;
 //#endregion
-//#region ../../../../node_modules/.pnpm/@effect-atom+atom@0.5.3_patch_hash=90a97dcb5aa93197ad34b41c932b405a7ba98679af6885de637f_c6b09d1bd6f76cb9fa1ec87ff9f87185/node_modules/@effect-atom/atom/dist/dts/AtomHttpApi.d.ts
-declare global {
-  interface ErrorConstructor {
-    stackTraceLimit: number;
-  }
-}
-/**
- * @since 1.0.0
- * @category Constructors
- */
-//#endregion
-//#region ../../../../node_modules/.pnpm/@effect-atom+atom@0.5.3_patch_hash=90a97dcb5aa93197ad34b41c932b405a7ba98679af6885de637f_c6b09d1bd6f76cb9fa1ec87ff9f87185/node_modules/@effect-atom/atom/dist/dts/AtomRpc.d.ts
-declare global {
-  interface ErrorConstructor {
-    stackTraceLimit: number;
-  }
-}
-/**
- * @since 1.0.0
- * @category Constructors
- */
+//#region ../../../common/async/dist/types/src/cleanup.d.ts
+type CleanupFn = () => void;
 //#endregion
 //#region ../../../common/context/dist/types/src/context.d.ts
 type ContextErrorHandler = (error: Error, ctx: Context$1) => void;
@@ -8863,18 +8844,6 @@ declare class Context$1 {
   [Symbol.asyncDispose](): Promise<void>;
 }
 //#endregion
-//#region ../../../common/effect/dist/types/src/internal/json-path.d.ts
-type JsonPath = string & {
-  __JsonPath: true;
-};
-/**
- * https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html
- */
-declare const JsonPath: Schema<JsonPath>;
-//#endregion
-//#region ../../../common/async/dist/types/src/cleanup.d.ts
-type CleanupFn = () => void;
-//#endregion
 //#region ../../../common/async/dist/types/src/events.d.ts
 type Effect = () => CleanupFn | undefined;
 interface EventEmitterLike {
@@ -9096,6 +9065,37 @@ interface ReadOnlyEvent<T$1 = void> {
   debounce(timeout?: number): Event$1<void>;
 }
 //#endregion
+//#region ../../../../node_modules/.pnpm/@effect-atom+atom@0.5.3_patch_hash=90a97dcb5aa93197ad34b41c932b405a7ba98679af6885de637f_c6b09d1bd6f76cb9fa1ec87ff9f87185/node_modules/@effect-atom/atom/dist/dts/AtomHttpApi.d.ts
+declare global {
+  interface ErrorConstructor {
+    stackTraceLimit: number;
+  }
+}
+/**
+ * @since 1.0.0
+ * @category Constructors
+ */
+//#endregion
+//#region ../../../../node_modules/.pnpm/@effect-atom+atom@0.5.3_patch_hash=90a97dcb5aa93197ad34b41c932b405a7ba98679af6885de637f_c6b09d1bd6f76cb9fa1ec87ff9f87185/node_modules/@effect-atom/atom/dist/dts/AtomRpc.d.ts
+declare global {
+  interface ErrorConstructor {
+    stackTraceLimit: number;
+  }
+}
+/**
+ * @since 1.0.0
+ * @category Constructors
+ */
+//#endregion
+//#region ../../../common/effect/dist/types/src/internal/json-path.d.ts
+type JsonPath = string & {
+  __JsonPath: true;
+};
+/**
+ * https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html
+ */
+declare const JsonPath: Schema<JsonPath>;
+//#endregion
 //#region ../echo/dist/types/src/internal/JsonSchema/json-schema-type.d.ts
 /**
  * Describes a schema for the JSON-schema objects stored in ECHO.
@@ -9729,19 +9729,72 @@ declare namespace Ref {
    */
   type Target<R$1> = R$1 extends Ref<infer U> ? U : never;
 }
+/**
+ * Load-source ceiling for a resolution request. Cheaper tiers are always probed first; the
+ * ceiling caps how far a request is allowed to reach:
+ * - `working-set`: synchronous, in-memory only. A miss settles `unavailable` immediately.
+ * - `disk`: probe the working set, then local storage; never the network.
+ * - `network`: probe the working set, disk, then fetch from peers.
+ *
+ * `unavailable` is always relative to the requested ceiling (disk-unavailable ≠ network-unavailable).
+ */
+type RefSource = 'working-set' | 'disk' | 'network';
+/**
+ * A stateful, closure-aware handle to an in-flight (or settled) reference resolution.
+ *
+ * `ready` means the entity is FULLY USABLE: its own body and its strong-dependency closure are all
+ * materialized. The body-vs-closure split is internal; `requesting` transparently covers "a
+ * dependency is still loading".
+ */
+interface RefResolverRequest {
+  /**
+   * `pending` is a one-way entry state (never re-entered). `requesting` means the body and/or
+   * closure is still loading. `ready` means fully usable. `unavailable` means unreachable at the
+   * requested ceiling.
+   */
+  readonly state: 'pending' | 'requesting' | 'ready' | 'unavailable';
+  /**
+   * Fires (deferred to a microtask) whenever {@link state} changes.
+   */
+  readonly stateChanged: Event$1<void>;
+  /**
+   * Synchronous snapshot of the resolved entity; defined iff `state === 'ready'`.
+   */
+  getResult(): AnyProperties | undefined;
+  /**
+   * Settles when `state ∈ {ready, unavailable}`.
+   */
+  wait(): Promise<AnyProperties | undefined>;
+  /**
+   * Decrements the refcount on the shared load op(s); cancels the underlying IO at zero.
+   */
+  abort(): void;
+}
 interface RefResolver {
+  /**
+   * Resolve a reference, returning a stateful handle. `source` is a required ceiling; cheaper
+   * tiers are always probed first.
+   */
+  resolve(uri: URI, options: {
+    source: RefSource;
+  }): RefResolverRequest;
   /**
    * Resolve ref synchronously from the objects in the working set.
    *
    * @param uri
    * @param load If true the resolver should attempt to load the object from disk.
    * @param onLoad Callback to call when the object is loaded.
+   * @deprecated Use {@link resolve} with `{ source: 'working-set' }`. Removed in Task 11.
    */
   resolveSync(uri: URI, load: boolean, onLoad?: () => void): AnyProperties | undefined;
   /**
    * Resolver ref asynchronously.
+   * @deprecated Use {@link resolve} with `{ source: 'network' }`. Removed in Task 11.
+   */
+  resolveLegacy(uri: URI): Promise<AnyProperties | undefined>;
+  /**
+   * @deprecated Use {@link resolve} + `Type.getSchema`. Removed in Task 11.
    */
-  resolve(uri: URI): Promise<AnyProperties | undefined>;
   resolveSchema(uri: URI): Promise<Schema.AnyNoContext | undefined>;
   /**
    * Resolve the source `Type.AnyEntity` entity for a type URI. Used by
@@ -9749,6 +9802,7 @@ interface RefResolver {
    * via `Obj.getType` / `Entity.getType`. Optional — resolvers that only
    * carry raw schemas may leave this unimplemented; the deserializer falls
    * back to leaving the type entity unset.
+   * @deprecated Use {@link resolve}. Removed in Task 11.
    */
   resolveType?(uri: URI): Promise<unknown | undefined>;
 }
@@ -10031,111 +10085,6 @@ declare const Collection: Obj$1<{
 }, Struct.Fields>;
 type Collection = InstanceType$1<typeof Collection>;
 //#endregion
-//#region ../echo/dist/types/src/QueryResult.d.ts
-/**
- * Individual query result entry.
- */
-type Entry$1<T$1> = {
-  id: string;
-  /**
-   * May not be present for remote results.
-   */
-  result?: T$1;
-  match?: {
-    /**
-     * Higher means better match.
-     */
-    rank: number;
-  };
-  /**
-   * Query resolution metadata.
-   */
-  resolution?: {
-    source: 'remote' | 'local' | 'index';
-    /**
-     * Query resolution time in milliseconds.
-     */
-    time: number;
-  };
-};
-type RunOptions = {
-  timeout?: number;
-};
-type SubscriptionOptions = {
-  /**
-   * Fire the callback immediately.
-   */
-  fire?: boolean;
-};
-interface QueryResult<T$1> {
-  /**
-   * Currently available results along with their match metadata.
-   */
-  readonly entries: Entry$1<T$1>[];
-  /**
-   * Currently available results.
-   */
-  readonly results: T$1[];
-  /**
-   * Returns all known results.
-   */
-  run(opts?: RunOptions): Promise<T$1[]>;
-  /**
-   * Returns all known results along with their match metadata.
-   */
-  runEntries(opts?: RunOptions): Promise<Entry$1<T$1>[]>;
-  /**
-   * Returns currently available results synchronously.
-   */
-  runSync(): T$1[];
-  /**
-   * Returns currently available results synchronously along with their match metadata.
-   */
-  runSyncEntries(): Entry$1<T$1>[];
-  /**
-   * Returns first result.
-   */
-  first(opts?: RunOptions): Promise<T$1>;
-  /**
-   * Returns first result if there is one.
-   */
-  firstOrUndefined(opts?: RunOptions): Promise<T$1 | undefined>;
-  /**
-   * Subscribes to changes in query results.
-   */
-  subscribe(callback?: (query: QueryResult<T$1>) => void, opts?: SubscriptionOptions): CleanupFn;
-  /**
-   * Self-updating atom. Updates automatically when query results change.
-   *
-   * Memoized per QueryResult instance — repeated accesses on the same instance return the same
-   * Atom. Safe only when the QueryResult is itself held stable across re-renders (e.g. behind a
-   * `useMemo`). It must NOT be used in graph-builder connectors/actions or other atom computes,
-   * where `db.query(...)` is called fresh on each re-evaluation: every run constructs a new
-   * QueryResult and so a new atom + subscription, leaking the previous ones. Use the memoized
-   * {@link atom} family there instead.
-   */
-  readonly atom: Atom<T$1[]>;
-}
-//#endregion
-//#region ../echo/dist/types/src/Feed.d.ts
-/**
- * Runtime schema for a Feed object.
- *
- * @example
- * ```ts
- * const feed = Obj.make(Feed.Feed, { name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
- * ```
- */
-declare const Feed: Obj$1<{
-  readonly name?: string | undefined;
-  readonly kind?: string | undefined;
-  readonly namespace?: "data" | "trace" | undefined;
-}, Struct.Fields>;
-/**
- * TypeScript instance type for a Feed object.
- */
-type Feed = InstanceType$1<typeof Feed>;
-//#endregion
 //#region ../echo/dist/types/src/View.d.ts
 /**
  * Views are generated or user-defined projections of a schema's properties.
@@ -10430,6 +10379,111 @@ declare const from: (...args: [(Database | Database[] | Feed | Feed[] | Any$1 |
  */
 declare const pretty: (query: Any$1) => string;
 //#endregion
+//#region ../echo/dist/types/src/QueryResult.d.ts
+/**
+ * Individual query result entry.
+ */
+type Entry$1<T$1> = {
+  id: string;
+  /**
+   * May not be present for remote results.
+   */
+  result?: T$1;
+  match?: {
+    /**
+     * Higher means better match.
+     */
+    rank: number;
+  };
+  /**
+   * Query resolution metadata.
+   */
+  resolution?: {
+    source: 'remote' | 'local' | 'index';
+    /**
+     * Query resolution time in milliseconds.
+     */
+    time: number;
+  };
+};
+type RunOptions = {
+  timeout?: number;
+};
+type SubscriptionOptions = {
+  /**
+   * Fire the callback immediately.
+   */
+  fire?: boolean;
+};
+interface QueryResult<T$1> {
+  /**
+   * Currently available results along with their match metadata.
+   */
+  readonly entries: Entry$1<T$1>[];
+  /**
+   * Currently available results.
+   */
+  readonly results: T$1[];
+  /**
+   * Returns all known results.
+   */
+  run(opts?: RunOptions): Promise<T$1[]>;
+  /**
+   * Returns all known results along with their match metadata.
+   */
+  runEntries(opts?: RunOptions): Promise<Entry$1<T$1>[]>;
+  /**
+   * Returns currently available results synchronously.
+   */
+  runSync(): T$1[];
+  /**
+   * Returns currently available results synchronously along with their match metadata.
+   */
+  runSyncEntries(): Entry$1<T$1>[];
+  /**
+   * Returns first result.
+   */
+  first(opts?: RunOptions): Promise<T$1>;
+  /**
+   * Returns first result if there is one.
+   */
+  firstOrUndefined(opts?: RunOptions): Promise<T$1 | undefined>;
+  /**
+   * Subscribes to changes in query results.
+   */
+  subscribe(callback?: (query: QueryResult<T$1>) => void, opts?: SubscriptionOptions): CleanupFn;
+  /**
+   * Self-updating atom. Updates automatically when query results change.
+   *
+   * Memoized per QueryResult instance — repeated accesses on the same instance return the same
+   * Atom. Safe only when the QueryResult is itself held stable across re-renders (e.g. behind a
+   * `useMemo`). It must NOT be used in graph-builder connectors/actions or other atom computes,
+   * where `db.query(...)` is called fresh on each re-evaluation: every run constructs a new
+   * QueryResult and so a new atom + subscription, leaking the previous ones. Use the memoized
+   * {@link atom} family there instead.
+   */
+  readonly atom: Atom<T$1[]>;
+}
+//#endregion
+//#region ../echo/dist/types/src/Feed.d.ts
+/**
+ * Runtime schema for a Feed object.
+ *
+ * @example
+ * ```ts
+ * const feed = Obj.make(Feed.Feed, { name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
+ * ```
+ */
+declare const Feed: Obj$1<{
+  readonly name?: string | undefined;
+  readonly kind?: string | undefined;
+  readonly namespace?: "data" | "trace" | undefined;
+}, Struct.Fields>;
+/**
+ * TypeScript instance type for a Feed object.
+ */
+type Feed = InstanceType$1<typeof Feed>;
+//#endregion
 //#region ../echo/dist/types/src/Registry.d.ts
 /**
  * Identifier denoting an ECHO Registry.
@@ -10698,6 +10752,17 @@ interface Database extends Queryable {
    * Removes object from the database.
    */
   remove(obj: Unknown): void;
+  /**
+   * Appends entities to a feed.
+   *
+   * The feed must already be stored in the database (added via {@link add}); its underlying
+   * queue is addressed by the feed object's URI.
+   */
+  appendToFeed(feed: Feed, entities: Unknown[]): Promise<void>;
+  /**
+   * Removes entities from a feed.
+   */
+  deleteFromFeed(feed: Feed, entities: Unknown[]): Promise<void>;
   /**
    * Wait for all pending changes to be saved to disk.
    * Optionaly waits for changes to be propagated to indexes and event handlers.