@logixjs/query 0.0.1

package/dist/Engine.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/Engine.ts
+var Engine_exports = {};
+__export(Engine_exports, {
+  Engine: () => Engine
+});
+module.exports = __toCommonJS(Engine_exports);
+var import_effect2 = require("effect");
+
+// src/internal/middleware/middleware.ts
+var import_effect = require("effect");
+var middleware = (config) => /* @__PURE__ */ (() => {
+  let cachedEngine;
+  return (op) => {
+    if (op.kind !== "service" && op.kind !== "trait-source" || !op.meta?.resourceId || !op.meta.keyHash) {
+      return op.effect;
+    }
+    const resourceId = op.meta.resourceId;
+    if (config?.useFor && !config.useFor(resourceId)) {
+      return op.effect;
+    }
+    const keyHash = op.meta.keyHash;
+    if (cachedEngine) {
+      if (cachedEngine.fetchFast) {
+        return cachedEngine.fetchFast(resourceId, keyHash, op.effect);
+      }
+      return cachedEngine.fetch({ resourceId, keyHash, effect: op.effect });
+    }
+    return import_effect.Effect.serviceOption(Engine).pipe(
+      import_effect.Effect.flatMap((engineOpt) => {
+        if (import_effect.Option.isNone(engineOpt)) {
+          return import_effect.Effect.fail(
+            new Error(
+              `[Query.Engine.middleware] Missing Query.Engine in the Runtime scope; please provide Query.Engine.layer(Query.TanStack.engine(new QueryClient())) (recommended) or Query.Engine.layer(customEngine).`
+            )
+          );
+        }
+        cachedEngine = engineOpt.value;
+        if (cachedEngine.fetchFast) {
+          return cachedEngine.fetchFast(resourceId, keyHash, op.effect);
+        }
+        return cachedEngine.fetch({ resourceId, keyHash, effect: op.effect });
+      })
+    );
+  };
+})();
+
+// src/Engine.ts
+var EngineTagImpl = class extends import_effect2.Context.Tag("@logixjs/query/Engine")() {
+};
+var Engine = Object.assign(EngineTagImpl, {
+  layer: (engine) => import_effect2.Layer.succeed(EngineTagImpl, engine),
+  middleware: (config) => middleware(config)
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Engine
+});
+//# sourceMappingURL=Engine.cjs.map

package/dist/Engine.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Engine.ts","../src/internal/middleware/middleware.ts"],"sourcesContent":["import type * as EffectOp from '@logixjs/core/EffectOp'\nimport { Context, Effect, Layer, Option } from 'effect'\nimport { middleware as middlewareImpl, type MiddlewareConfig } from './internal/middleware/middleware.js'\n\nexport type InvalidateRequest =\n  | { readonly kind: 'byResource'; readonly resourceId: string }\n  | { readonly kind: 'byParams'; readonly resourceId: string; readonly keyHash: string }\n  | { readonly kind: 'byTag'; readonly tag: string }\n\nexport interface Engine {\n  readonly fetch: <A>(args: {\n    readonly resourceId: string\n    readonly keyHash: string\n    readonly effect: Effect.Effect<A, unknown, any>\n    /**\n     * MUST be serializable and slim; recommended default is undefined (lazy),\n     * and only populate it when diagnostics/devtools require it.\n     */\n    readonly meta?: unknown\n  }) => Effect.Effect<A, unknown, any>\n\n  /**\n   * perf: optional fast path to avoid allocations on the hot path.\n   * Semantics must match `fetch({ ... })`.\n   */\n  readonly fetchFast?: <A>(\n    resourceId: string,\n    keyHash: string,\n    effect: Effect.Effect<A, unknown, any>,\n    meta?: unknown,\n  ) => Effect.Effect<A, unknown, any>\n\n  readonly invalidate: (request: InvalidateRequest) => Effect.Effect<void, unknown, any>\n\n  /**\n   * Read-only fast path: must not trigger IO; used to short-circuit to success before refresh,\n   * avoiding loading jitter.\n   */\n  readonly peekFresh?: <A>(args: {\n    readonly resourceId: string\n    readonly keyHash: string\n  }) => Effect.Effect<Option.Option<A>, never, any>\n}\n\nclass EngineTagImpl extends Context.Tag('@logixjs/query/Engine')<EngineTagImpl, Engine>() {}\n\nexport const Engine = Object.assign(EngineTagImpl, {\n  layer: (engine: Engine): Layer.Layer<EngineTagImpl, never, never> => Layer.succeed(EngineTagImpl, engine),\n  middleware: (config?: MiddlewareConfig): EffectOp.Middleware => middlewareImpl(config),\n})\n\nexport type { MiddlewareConfig }\n","import type * as EffectOp from '@logixjs/core/EffectOp'\nimport { Effect, Option } from 'effect'\nimport { Engine } from '../../Engine.js'\nimport type { Engine as EngineService } from '../../Engine.js'\n\nexport interface MiddlewareConfig {\n  /**\n   * Default: only applies to EffectOp that carries resourceId+keyHash (from StateTrait.source).\n   * Optional: further filter by resourceId.\n   */\n  readonly useFor?: (resourceId: string) => boolean\n}\n\n/**\n * Query middleware (EffectOp): external engine takeover point.\n * - Delegates ResourceSpec.load execution to Engine (cache / in-flight dedupe / invalidation, etc.)\n * - Still preserves Logix Runtime's keyHash gating and ResourceSnapshot source-of-truth semantics\n */\nexport const middleware = (config?: MiddlewareConfig): EffectOp.Middleware =>\n  (() => {\n    // perf: within the same Runtime instance, Engine injection is stable.\n    // Cache it in the middleware closure to avoid a Context lookup on every fetch.\n    let cachedEngine: EngineService | undefined\n\n    return (op) => {\n      if ((op.kind !== 'service' && op.kind !== 'trait-source') || !op.meta?.resourceId || !op.meta.keyHash) {\n        return op.effect as any\n      }\n\n      const resourceId = op.meta.resourceId\n      if (config?.useFor && !config.useFor(resourceId)) {\n        return op.effect as any\n      }\n\n      const keyHash = op.meta.keyHash as string\n\n      if (cachedEngine) {\n        if (cachedEngine.fetchFast) {\n          return cachedEngine.fetchFast(resourceId, keyHash, op.effect as any)\n        }\n        return cachedEngine.fetch({ resourceId, keyHash, effect: op.effect as any })\n      }\n\n      return Effect.serviceOption(Engine).pipe(\n        Effect.flatMap((engineOpt) => {\n          if (Option.isNone(engineOpt)) {\n            return Effect.fail(\n              new Error(\n                `[Query.Engine.middleware] Missing Query.Engine in the Runtime scope; please provide Query.Engine.layer(Query.TanStack.engine(new QueryClient())) (recommended) or Query.Engine.layer(customEngine).`,\n              ),\n            )\n          }\n          cachedEngine = engineOpt.value\n          if (cachedEngine.fetchFast) {\n            return cachedEngine.fetchFast(resourceId, keyHash, op.effect as any)\n          }\n          return cachedEngine.fetch({ resourceId, keyHash, effect: op.effect as any })\n        }),\n      ) as any\n    }\n  })()\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,IAAAA,iBAA+C;;;ACA/C,oBAA+B;AAiBxB,IAAM,aAAa,CAAC,WACxB,uBAAM;AAGL,MAAI;AAEJ,SAAO,CAAC,OAAO;AACb,QAAK,GAAG,SAAS,aAAa,GAAG,SAAS,kBAAmB,CAAC,GAAG,MAAM,cAAc,CAAC,GAAG,KAAK,SAAS;AACrG,aAAO,GAAG;AAAA,IACZ;AAEA,UAAM,aAAa,GAAG,KAAK;AAC3B,QAAI,QAAQ,UAAU,CAAC,OAAO,OAAO,UAAU,GAAG;AAChD,aAAO,GAAG;AAAA,IACZ;AAEA,UAAM,UAAU,GAAG,KAAK;AAExB,QAAI,cAAc;AAChB,UAAI,aAAa,WAAW;AAC1B,eAAO,aAAa,UAAU,YAAY,SAAS,GAAG,MAAa;AAAA,MACrE;AACA,aAAO,aAAa,MAAM,EAAE,YAAY,SAAS,QAAQ,GAAG,OAAc,CAAC;AAAA,IAC7E;AAEA,WAAO,qBAAO,cAAc,MAAM,EAAE;AAAA,MAClC,qBAAO,QAAQ,CAAC,cAAc;AAC5B,YAAI,qBAAO,OAAO,SAAS,GAAG;AAC5B,iBAAO,qBAAO;AAAA,YACZ,IAAI;AAAA,cACF;AAAA,YACF;AAAA,UACF;AAAA,QACF;AACA,uBAAe,UAAU;AACzB,YAAI,aAAa,WAAW;AAC1B,iBAAO,aAAa,UAAU,YAAY,SAAS,GAAG,MAAa;AAAA,QACrE;AACA,eAAO,aAAa,MAAM,EAAE,YAAY,SAAS,QAAQ,GAAG,OAAc,CAAC;AAAA,MAC7E,CAAC;AAAA,IACH;AAAA,EACF;AACF,GAAG;;;ADhBL,IAAM,gBAAN,cAA4B,uBAAQ,IAAI,uBAAuB,EAAyB,EAAE;AAAC;AAEpF,IAAM,SAAS,OAAO,OAAO,eAAe;AAAA,EACjD,OAAO,CAAC,WAA6D,qBAAM,QAAQ,eAAe,MAAM;AAAA,EACxG,YAAY,CAAC,WAAmD,WAAe,MAAM;AACvF,CAAC;","names":["import_effect"]}

package/dist/Engine.d.cts

@@ -0,0 +1,57 @@
+import * as EffectOp from '@logixjs/core/EffectOp';
+import { Effect, Option, Context, Layer } from 'effect';
+
+interface MiddlewareConfig {
+    /**
+     * Default: only applies to EffectOp that carries resourceId+keyHash (from StateTrait.source).
+     * Optional: further filter by resourceId.
+     */
+    readonly useFor?: (resourceId: string) => boolean;
+}
+
+type InvalidateRequest = {
+    readonly kind: 'byResource';
+    readonly resourceId: string;
+} | {
+    readonly kind: 'byParams';
+    readonly resourceId: string;
+    readonly keyHash: string;
+} | {
+    readonly kind: 'byTag';
+    readonly tag: string;
+};
+declare const EngineTagImpl_base: Context.TagClass<EngineTagImpl, "@logixjs/query/Engine", Engine>;
+declare class EngineTagImpl extends EngineTagImpl_base {
+}
+interface Engine {
+    readonly fetch: <A>(args: {
+        readonly resourceId: string;
+        readonly keyHash: string;
+        readonly effect: Effect.Effect<A, unknown, any>;
+        /**
+         * MUST be serializable and slim; recommended default is undefined (lazy),
+         * and only populate it when diagnostics/devtools require it.
+         */
+        readonly meta?: unknown;
+    }) => Effect.Effect<A, unknown, any>;
+    /**
+     * perf: optional fast path to avoid allocations on the hot path.
+     * Semantics must match `fetch({ ... })`.
+     */
+    readonly fetchFast?: <A>(resourceId: string, keyHash: string, effect: Effect.Effect<A, unknown, any>, meta?: unknown) => Effect.Effect<A, unknown, any>;
+    readonly invalidate: (request: InvalidateRequest) => Effect.Effect<void, unknown, any>;
+    /**
+     * Read-only fast path: must not trigger IO; used to short-circuit to success before refresh,
+     * avoiding loading jitter.
+     */
+    readonly peekFresh?: <A>(args: {
+        readonly resourceId: string;
+        readonly keyHash: string;
+    }) => Effect.Effect<Option.Option<A>, never, any>;
+}
+declare const Engine: typeof EngineTagImpl & {
+    layer: (engine: Engine) => Layer.Layer<EngineTagImpl, never, never>;
+    middleware: (config?: MiddlewareConfig) => EffectOp.Middleware;
+};
+
+export { Engine, type InvalidateRequest, type MiddlewareConfig };

package/dist/Engine.d.ts

@@ -0,0 +1,57 @@
+import * as EffectOp from '@logixjs/core/EffectOp';
+import { Effect, Option, Context, Layer } from 'effect';
+
+interface MiddlewareConfig {
+    /**
+     * Default: only applies to EffectOp that carries resourceId+keyHash (from StateTrait.source).
+     * Optional: further filter by resourceId.
+     */
+    readonly useFor?: (resourceId: string) => boolean;
+}
+
+type InvalidateRequest = {
+    readonly kind: 'byResource';
+    readonly resourceId: string;
+} | {
+    readonly kind: 'byParams';
+    readonly resourceId: string;
+    readonly keyHash: string;
+} | {
+    readonly kind: 'byTag';
+    readonly tag: string;
+};
+declare const EngineTagImpl_base: Context.TagClass<EngineTagImpl, "@logixjs/query/Engine", Engine>;
+declare class EngineTagImpl extends EngineTagImpl_base {
+}
+interface Engine {
+    readonly fetch: <A>(args: {
+        readonly resourceId: string;
+        readonly keyHash: string;
+        readonly effect: Effect.Effect<A, unknown, any>;
+        /**
+         * MUST be serializable and slim; recommended default is undefined (lazy),
+         * and only populate it when diagnostics/devtools require it.
+         */
+        readonly meta?: unknown;
+    }) => Effect.Effect<A, unknown, any>;
+    /**
+     * perf: optional fast path to avoid allocations on the hot path.
+     * Semantics must match `fetch({ ... })`.
+     */
+    readonly fetchFast?: <A>(resourceId: string, keyHash: string, effect: Effect.Effect<A, unknown, any>, meta?: unknown) => Effect.Effect<A, unknown, any>;
+    readonly invalidate: (request: InvalidateRequest) => Effect.Effect<void, unknown, any>;
+    /**
+     * Read-only fast path: must not trigger IO; used to short-circuit to success before refresh,
+     * avoiding loading jitter.
+     */
+    readonly peekFresh?: <A>(args: {
+        readonly resourceId: string;
+        readonly keyHash: string;
+    }) => Effect.Effect<Option.Option<A>, never, any>;
+}
+declare const Engine: typeof EngineTagImpl & {
+    layer: (engine: Engine) => Layer.Layer<EngineTagImpl, never, never>;
+    middleware: (config?: MiddlewareConfig) => EffectOp.Middleware;
+};
+
+export { Engine, type InvalidateRequest, type MiddlewareConfig };

package/dist/Engine.js

@@ -0,0 +1,8 @@
+import {
+  Engine
+} from "./chunk-THVAADR2.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  Engine
+};
+//# sourceMappingURL=Engine.js.map

package/dist/Engine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/Query.cjs

@@ -0,0 +1,457 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/Query.ts
+var Query_exports = {};
+__export(Query_exports, {
+  make: () => make
+});
+module.exports = __toCommonJS(Query_exports);
+var Logix4 = __toESM(require("@logixjs/core"), 1);
+var import_effect5 = require("effect");
+
+// src/internal/logics/auto-trigger.ts
+var Logix = __toESM(require("@logixjs/core"), 1);
+var import_effect3 = require("effect");
+
+// src/Engine.ts
+var import_effect2 = require("effect");
+
+// src/internal/middleware/middleware.ts
+var import_effect = require("effect");
+var middleware = (config) => /* @__PURE__ */ (() => {
+  let cachedEngine;
+  return (op) => {
+    if (op.kind !== "service" && op.kind !== "trait-source" || !op.meta?.resourceId || !op.meta.keyHash) {
+      return op.effect;
+    }
+    const resourceId = op.meta.resourceId;
+    if (config?.useFor && !config.useFor(resourceId)) {
+      return op.effect;
+    }
+    const keyHash = op.meta.keyHash;
+    if (cachedEngine) {
+      if (cachedEngine.fetchFast) {
+        return cachedEngine.fetchFast(resourceId, keyHash, op.effect);
+      }
+      return cachedEngine.fetch({ resourceId, keyHash, effect: op.effect });
+    }
+    return import_effect.Effect.serviceOption(Engine).pipe(
+      import_effect.Effect.flatMap((engineOpt) => {
+        if (import_effect.Option.isNone(engineOpt)) {
+          return import_effect.Effect.fail(
+            new Error(
+              `[Query.Engine.middleware] Missing Query.Engine in the Runtime scope; please provide Query.Engine.layer(Query.TanStack.engine(new QueryClient())) (recommended) or Query.Engine.layer(customEngine).`
+            )
+          );
+        }
+        cachedEngine = engineOpt.value;
+        if (cachedEngine.fetchFast) {
+          return cachedEngine.fetchFast(resourceId, keyHash, op.effect);
+        }
+        return cachedEngine.fetch({ resourceId, keyHash, effect: op.effect });
+      })
+    );
+  };
+})();
+
+// src/Engine.ts
+var EngineTagImpl = class extends import_effect2.Context.Tag("@logixjs/query/Engine")() {
+};
+var Engine = Object.assign(EngineTagImpl, {
+  layer: (engine) => import_effect2.Layer.succeed(EngineTagImpl, engine),
+  middleware: (config) => middleware(config)
+});
+
+// src/internal/logics/auto-trigger.ts
+var defaultTriggers = ["onMount", "onKeyChange"];
+var getTriggers = (triggers) => triggers ?? defaultTriggers;
+var isManualOnly = (triggers) => triggers.length === 1 && triggers[0] === "manual";
+var getSnapshotKeyHash = (snapshot) => {
+  if (!snapshot || typeof snapshot !== "object") return void 0;
+  const keyHash = snapshot.keyHash;
+  return typeof keyHash === "string" ? keyHash : void 0;
+};
+var getSnapshotStatus = (snapshot) => {
+  if (!snapshot || typeof snapshot !== "object") return void 0;
+  const status = snapshot.status;
+  return typeof status === "string" ? status : void 0;
+};
+var autoTrigger = (module2, config) => module2.logic(($) => {
+  const pending = /* @__PURE__ */ new Map();
+  const lastKeyHash = /* @__PURE__ */ new Map();
+  const hydrateFromFreshCache = (name, q, keyHash) => import_effect3.Effect.gen(function* () {
+    const engineOpt = yield* import_effect3.Effect.serviceOption(Engine);
+    if (engineOpt._tag === "None") return false;
+    const engine = engineOpt.value;
+    if (!engine.peekFresh) return false;
+    const dataOpt = yield* engine.peekFresh({
+      resourceId: q.resource.id,
+      keyHash
+    });
+    if (dataOpt._tag === "None") return false;
+    const snapshot = Logix.Resource.Snapshot.success({
+      keyHash,
+      data: dataOpt.value
+    });
+    yield* $.state.mutate((draft) => {
+      ;
+      draft.queries[name] = snapshot;
+    });
+    return true;
+  });
+  const cancelPending = (name) => import_effect3.Effect.gen(function* () {
+    const prev = pending.get(name);
+    if (!prev) return;
+    pending.delete(name);
+    yield* import_effect3.Fiber.interruptFork(prev);
+  });
+  const sourcePathOf = (name) => `queries.${name}`;
+  const refresh = (name, options) => $.traits.source.refresh(sourcePathOf(name), options);
+  const scheduleDebounced = (name, ms) => import_effect3.Effect.gen(function* () {
+    yield* cancelPending(name);
+    const fiber = yield* import_effect3.Effect.forkScoped(
+      import_effect3.Effect.sleep(import_effect3.Duration.millis(ms)).pipe(
+        import_effect3.Effect.zipRight(refresh(name)),
+        import_effect3.Effect.ensuring(import_effect3.Effect.sync(() => pending.delete(name))),
+        import_effect3.Effect.catchAllCause(() => import_effect3.Effect.void)
+      )
+    );
+    pending.set(name, fiber);
+  });
+  const computeKeyHash = (state, q) => {
+    const getAtPath = (root, path) => {
+      const parts = path.split(".");
+      let cur = root;
+      for (const p of parts) {
+        if (cur == null) return void 0;
+        cur = cur[p];
+      }
+      return cur;
+    };
+    try {
+      const keyState = { params: state.params, ui: state.ui };
+      const args = q.deps.map((dep) => getAtPath(keyState, dep));
+      const key = q.key(...args);
+      if (key === void 0) return void 0;
+      return Logix.Resource.keyHash(key);
+    } catch {
+      return void 0;
+    }
+  };
+  const maybeAutoRefresh = (phase, stateOverride) => import_effect3.Effect.gen(function* () {
+    const state = stateOverride ?? (yield* $.state.read);
+    for (const [name, q] of Object.entries(config.queries)) {
+      const queryName = name;
+      const triggers = getTriggers(q.triggers);
+      if (isManualOnly(triggers)) {
+        continue;
+      }
+      if (phase === "mount" && !triggers.includes("onMount")) {
+        continue;
+      }
+      if (phase === "keyChange" && !triggers.includes("onKeyChange")) {
+        continue;
+      }
+      const keyHash = computeKeyHash(state, q);
+      const snapshot = state?.queries?.[queryName];
+      const snapshotKeyHash = getSnapshotKeyHash(snapshot);
+      const snapshotStatus = getSnapshotStatus(snapshot);
+      if (keyHash === void 0) {
+        lastKeyHash.set(queryName, void 0);
+        continue;
+      }
+      const last = lastKeyHash.get(queryName);
+      if (snapshotStatus && snapshotStatus !== "idle" && snapshotKeyHash === keyHash && last === keyHash) {
+        continue;
+      }
+      if (snapshotStatus && snapshotStatus !== "idle" && snapshotKeyHash === keyHash) {
+        lastKeyHash.set(queryName, keyHash);
+        continue;
+      }
+      lastKeyHash.set(queryName, keyHash);
+      const hydrated = yield* hydrateFromFreshCache(queryName, q, keyHash);
+      if (hydrated) {
+        yield* cancelPending(queryName);
+        continue;
+      }
+      const debounceMs = q.debounceMs ?? 0;
+      if (phase === "keyChange" && debounceMs > 0) {
+        yield* scheduleDebounced(queryName, debounceMs);
+      } else {
+        yield* cancelPending(queryName);
+        yield* refresh(queryName);
+      }
+    }
+  });
+  const refreshAll = (options) => import_effect3.Effect.forEach(
+    Object.keys(config.queries),
+    (name) => cancelPending(name).pipe(import_effect3.Effect.zipRight(refresh(name, options)))
+  ).pipe(import_effect3.Effect.asVoid);
+  const setup = $.lifecycle.onStart(maybeAutoRefresh("mount"));
+  const run = import_effect3.Effect.suspend(
+    () => import_effect3.Effect.all(
+      [
+        // params/ui changes: handled by Query's default logic, avoiding scattered UI-side useEffect triggers.
+        $.onAction("setParams").runFork(
+          (action) => import_effect3.Effect.gen(function* () {
+            const state = yield* $.state.read;
+            const next = { ...state, params: action.payload };
+            yield* maybeAutoRefresh("keyChange", next);
+          })
+        ),
+        $.onAction("setUi").runFork(
+          (action) => import_effect3.Effect.gen(function* () {
+            const state = yield* $.state.read;
+            const next = { ...state, ui: action.payload };
+            yield* maybeAutoRefresh("keyChange", next);
+          })
+        ),
+        // Manual refresh: not restricted by triggers (manual-only still allows explicit refresh).
+        $.onAction("refresh").runFork(
+          (action) => import_effect3.Effect.gen(function* () {
+            const target = action.payload;
+            if (typeof target === "string" && target.length > 0) {
+              yield* cancelPending(target);
+              yield* refresh(target, { force: true });
+            } else {
+              yield* refreshAll({ force: true });
+            }
+          })
+        )
+      ],
+      { concurrency: "unbounded" }
+    ).pipe(import_effect3.Effect.asVoid)
+  );
+  return { setup, run };
+});
+
+// src/internal/logics/invalidate.ts
+var Logix2 = __toESM(require("@logixjs/core"), 1);
+var import_effect4 = require("effect");
+var toInvalidateTargets = (request, queries) => {
+  if (request.kind === "byResource") {
+    return Object.entries(queries).filter(([, q]) => q.resource.id === request.resourceId).map(([name, q]) => ({ name, resourceId: q.resource.id }));
+  }
+  if (request.kind === "byParams") {
+    return Object.entries(queries).filter(([, q]) => q.resource.id === request.resourceId).map(([name, q]) => ({ name, resourceId: q.resource.id }));
+  }
+  const entries = Object.entries(queries);
+  const tagged = entries.filter(([, q]) => Array.isArray(q.tags) && q.tags.includes(request.tag));
+  const selected = tagged.length > 0 ? tagged : entries;
+  return selected.map(([name, q]) => ({ name, resourceId: q.resource.id }));
+};
+var invalidate = (module2, config) => module2.logic(
+  ($) => import_effect4.Effect.gen(function* () {
+    yield* $.onAction("invalidate").runFork(
+      (action) => import_effect4.Effect.gen(function* () {
+        const request = action.payload;
+        yield* Logix2.TraitLifecycle.scopedExecute($, {
+          kind: "query:invalidate",
+          request
+        });
+        const engineOpt = yield* import_effect4.Effect.serviceOption(Engine);
+        if (engineOpt._tag !== "None") {
+          yield* engineOpt.value.invalidate(request);
+        }
+        const targets = toInvalidateTargets(request, config.queries);
+        const sourcePathOf = (name) => `queries.${name}`;
+        yield* import_effect4.Effect.forEach(
+          targets,
+          (t) => $.traits.source.refresh(sourcePathOf(t.name), { force: true })
+        ).pipe(import_effect4.Effect.asVoid);
+      })
+    );
+  })
+);
+
+// src/Traits.ts
+var Logix3 = __toESM(require("@logixjs/core"), 1);
+var toStateTraitSpec = (input) => {
+  const out = {};
+  for (const [name, q] of Object.entries(input.queries)) {
+    const triggers = q.triggers ?? ["onMount", "onKeyChange"];
+    if (triggers.includes("manual") && triggers.length > 1) {
+      throw new Error(
+        `[Query.traits] "manual" must be exclusive, but got triggers=[${triggers.join(", ")}] for query "${name}".`
+      );
+    }
+    out[`queries.${name}`] = Logix3.StateTrait.source({
+      // deps: used for graph building/diagnostics/future reverse-closure; Query also reuses deps to converge triggers.
+      deps: q.deps,
+      resource: q.resource.id,
+      triggers,
+      debounceMs: q.debounceMs,
+      concurrency: q.concurrency === "exhaust" ? "exhaust-trailing" : q.concurrency,
+      key: (...depsValues) => q.key(...depsValues)
+    });
+  }
+  return out;
+};
+
+// src/Query.ts
+var InvalidateRequestSchema = import_effect5.Schema.Union(
+  import_effect5.Schema.Struct({
+    kind: import_effect5.Schema.Literal("byResource"),
+    resourceId: import_effect5.Schema.String
+  }),
+  import_effect5.Schema.Struct({
+    kind: import_effect5.Schema.Literal("byParams"),
+    resourceId: import_effect5.Schema.String,
+    keyHash: import_effect5.Schema.String
+  }),
+  import_effect5.Schema.Struct({
+    kind: import_effect5.Schema.Literal("byTag"),
+    tag: import_effect5.Schema.String
+  })
+);
+var assertQueryName = (name) => {
+  if (!name) {
+    throw new Error(`[Query.make] query name must be non-empty`);
+  }
+  if (name.includes(".")) {
+    throw new Error(`[Query.make] query name must not include "."; got "${name}"`);
+  }
+  if (name === "params" || name === "ui" || name === "queries") {
+    throw new Error(`[Query.make] query name "${name}" is reserved`);
+  }
+};
+var make = (id, config) => {
+  const queryBuilder = {
+    source: (q) => q
+  };
+  const queries = (() => {
+    const raw = config.queries;
+    if (!raw) return {};
+    return raw(queryBuilder);
+  })();
+  const queriesForTraits = queries;
+  for (const name of Object.keys(queries)) {
+    assertQueryName(name);
+  }
+  const RefreshTargetSchema = (() => {
+    const names = Object.keys(queries);
+    if (names.length === 0) return import_effect5.Schema.Never;
+    if (names.length === 1) {
+      return import_effect5.Schema.Literal(names[0]);
+    }
+    const asUnionMembers = (items) => {
+      if (items.length < 2) {
+        throw new Error(`[Query.make] internal error: expected at least 2 query names for union`);
+      }
+      return items;
+    };
+    const members = names.map((n) => import_effect5.Schema.Literal(n));
+    return import_effect5.Schema.Union(...asUnionMembers(members));
+  })();
+  const UiSchema = import_effect5.Schema.Unknown;
+  const QueriesSchema = import_effect5.Schema.Struct(
+    Object.fromEntries(Object.keys(queries).map((k) => [k, import_effect5.Schema.Unknown]))
+  );
+  const StateSchema = import_effect5.Schema.Struct({
+    params: config.params,
+    ui: UiSchema,
+    queries: QueriesSchema
+  });
+  const Actions = {
+    setParams: config.params,
+    setUi: UiSchema,
+    refresh: import_effect5.Schema.UndefinedOr(RefreshTargetSchema),
+    invalidate: InvalidateRequestSchema
+  };
+  const reducers = {
+    setParams: (state, action, sink) => {
+      sink?.("params");
+      return { ...state, params: action.payload ?? state.params };
+    },
+    setUi: (state, action, sink) => {
+      sink?.("ui");
+      return { ...state, ui: action.payload ?? state.ui };
+    },
+    refresh: (state) => state,
+    invalidate: (state) => state
+  };
+  const queryTraits = Object.keys(queriesForTraits).length > 0 ? toStateTraitSpec({ queries: queriesForTraits }) : void 0;
+  const traits = queryTraits || config.traits ? {
+    ...queryTraits,
+    ...config.traits
+  } : void 0;
+  const module2 = Logix4.Module.make(id, {
+    state: StateSchema,
+    actions: Actions,
+    reducers,
+    traits
+  });
+  const logics = [
+    autoTrigger(module2.tag, { queries: queriesForTraits }),
+    invalidate(module2.tag, { queries: queriesForTraits })
+  ];
+  const initial = (params) => ({
+    params: params ?? config.initialParams,
+    ui: config.ui ?? {},
+    queries: Object.fromEntries(
+      Object.keys(queries).map((k) => [k, Logix4.Resource.Snapshot.idle()])
+    )
+  });
+  const controller = {
+    make: (runtime) => {
+      const dispatch = runtime.dispatch;
+      const actions = module2.actions;
+      return {
+        runtime,
+        getState: runtime.getState,
+        dispatch,
+        controller: {
+          setParams: (params) => dispatch(actions.setParams(params)),
+          setUi: (ui) => dispatch(actions.setUi(ui)),
+          refresh: (target) => dispatch(actions.refresh(target)),
+          invalidate: (request) => dispatch(actions.invalidate(request))
+        }
+      };
+    }
+  };
+  module2.controller = controller;
+  const EXTEND_HANDLE = /* @__PURE__ */ Symbol.for("logix.module.handle.extend");
+  module2.tag[EXTEND_HANDLE] = (runtime, base) => {
+    const c = controller.make(runtime);
+    return {
+      ...base,
+      controller: c.controller
+    };
+  };
+  return module2.implement({
+    initial: initial(),
+    logics: [...logics]
+  });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  make
+});
+//# sourceMappingURL=Query.cjs.map