@mongrov/data-access 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mongrov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# @mongrov/data-access
+
+Named-query / mutation / event registry with engine dispatch for `@mongrov` apps.
+
+Screens never import storage engines. Instead, they read via `useAppQuery(name, input)` and write via `useAppMutation(name)` against a single **registry** the app assembles at startup. The provider dispatches to the right engine (DuckDB, RxDB, or KV) and Zod-parses the result before it reaches the UI.
+
+## Features
+
+- **Define API** — `defineQuery`, `defineMutation`, `defineEvent` produce typed handles with a `__kind` discriminator and engine-specific config (SQL for DuckDB, observable factory for RxDB, key builder for KV).
+- **Engine dispatch** — `duckdb` (analytics), `rxdb` (reactive stream), `kv` (single-key read). Apps wire concrete adapters into `DataAccessProvider`.
+- **Authorize gate** — optional `authorize(input, ctx)` runs before every query and mutation; `false` throws `AuthorizationError`.
+- **Tenant auto-binding** — `{ brand, familyId }` from the active `RequestContext` are merged into DuckDB params automatically. Screens never pass tenant.
+- **Invalidation event bus** — `mitt`-backed exact-match dispatch plus a glob wrapper (`hrv:*`, `sleep:**`); mutations declare `invalidates`, queries declare `invalidatedBy`, refetches happen automatically.
+- **Optimistic mutations** — `optimistic(input, ctx)` surfaces immediately as `data`; reverts on failure.
+- **Cache defaults** — 30s `staleTime`, 5min `gcTime`, overridable per query.
+- **ESLint plugin** — `no-storage-engine-imports` bans direct `@mongrov/db`, `@mongrov/analytics`, `@mongrov/collab` imports outside the registry directory.
+
+## Install
+
+```bash
+pnpm add @mongrov/data-access
+# Peer deps
+pnpm add @tanstack/react-query zod
+# Optional peers (only what you use)
+pnpm add @mongrov/db @mongrov/analytics react react-native eslint
+```
+
+## Registry pattern
+
+Assemble a registry once — typically under `src/data/` in your app.
+
+```ts
+// src/data/queries.ts
+import { defineQuery } from '@mongrov/data-access';
+import { z } from 'zod';
+
+export const hrvLast7Days = defineQuery({
+  engine: 'duckdb',
+  input: z.object({ userId: z.string() }),
+  output: z.array(z.object({ day: z.string(), rmssd: z.number() })),
+  sql: 'SELECT day, rmssd FROM hrv WHERE user_id = $userId AND brand = $brand AND family_id = $familyId ORDER BY day DESC LIMIT 7',
+  invalidatedBy: ['hrv:*'],
+  staleTime: 60_000,
+});
+```
+
+```ts
+// src/data/mutations.ts
+import { defineMutation } from '@mongrov/data-access';
+import { z } from 'zod';
+
+export const recordHrvSample = defineMutation({
+  input: z.object({ rmssd: z.number(), ts: z.string() }),
+  output: z.object({ id: z.string() }),
+  exec: async (input, ctx) => {
+    // Direct engine access is legal here because this file lives in
+    // src/data/, which the ESLint rule's `allowedDirs` grants an
+    // exception to.
+    return await analytics.insert('hrv', { ...input, userId: ctx.requesterUserId });
+  },
+  invalidates: ['hrv:sample:added'],
+});
+```
+
+```ts
+// src/data/registry.ts
+import { hrvLast7Days } from './queries';
+import { recordHrvSample } from './mutations';
+
+export const registry = {
+  queries: { 'hrv.last7Days': hrvLast7Days },
+  mutations: { 'hrv.record': recordHrvSample },
+  events: {},
+} as const;
+```
+
+Mount the provider at the app root:
+
+```tsx
+// src/app/_layout.tsx
+import { DataAccessProvider } from '@mongrov/data-access';
+import { registry } from '@/data/registry';
+import { analyticsEngine } from '@/data/engines';
+
+export default function RootLayout() {
+  return (
+    <DataAccessProvider
+      registry={registry}
+      engines={{ duckdb: analyticsEngine }}
+      context={() => ({
+        requesterUserId: session.userId,
+        brand: 'zivaone',
+        familyId: session.familyId,
+        now: () => new Date(),
+      })}
+    >
+      <Slot />
+    </DataAccessProvider>
+  );
+}
+```
+
+Screens consume via hooks — no engine imports:
+
+```tsx
+// src/features/hrv/screen.tsx
+import { useAppQuery, useAppMutation } from '@mongrov/data-access';
+
+export function HrvScreen() {
+  const { data, loading, error } = useAppQuery<
+    { userId: string },
+    Array<{ day: string; rmssd: number }>
+  >('hrv.last7Days', { userId: 'me' });
+
+  const record = useAppMutation<{ rmssd: number; ts: string }, { id: string }>('hrv.record');
+
+  if (loading) return <ActivityIndicator />;
+  if (error) return <Text>{error.message}</Text>;
+
+  return (
+    <>
+      <List data={data} />
+      <Button
+        title="Record sample"
+        onPress={() => record.mutate({ rmssd: 42, ts: new Date().toISOString() })}
+      />
+    </>
+  );
+}
+```
+
+## API
+
+### `defineQuery(config)`
+
+Returns a `QueryDefinition<Input, Output>` handle with `__kind: 'query'`. Config union by `engine`:
+
+| Field           | duckdb        | rxdb                                | kv                          |
+| --------------- | ------------- | ----------------------------------- | --------------------------- |
+| Required        | `sql: string` | `query: (db, input) => Observable`  | `keyBuilder: (input) => string` |
+| Common          | `output: ZodType` (required), `input?: ZodType`, `invalidatedBy?: string[]`, `authorize?`, `staleTime?`, `gcTime?` |||
+
+- **duckdb** — params include Zod-parsed input **plus** `brand` and `familyId` from `RequestContext`, injected as `$brand` / `$familyId` for `analytics.execute(sql, params)`.
+- **rxdb** — returned observable is subscribed in `useAppQuery`. Each emission is Zod-parsed. Unsubscribes on unmount.
+- **kv** — `keyBuilder(input)` produces the storage key; the engine's `get(key)` returns the value. No automatic invalidation.
+
+### `defineMutation(config)`
+
+Returns a `MutationDefinition<Input, Output>` handle with `__kind: 'mutation'`.
+
+- `exec(input, ctx) => Promise<Output>` — required.
+- `invalidates?: string[]` — event bus patterns fired on success.
+- `authorize?(input, ctx) => boolean | Promise<boolean>` — false throws `AuthorizationError`.
+- `optimistic?(input, ctx) => Output` — surfaces as `data` while pending; reverts on failure.
+- `input?` / `output?` — Zod schemas; validation is applied on both sides.
+
+### `defineEvent<TPayload>()`
+
+Returns an `EventDefinition<TPayload>` handle with `__kind: 'event'`. Payload type flows through `useAppEvent`.
+
+### `useAppQuery<Input, Output>(name, input?)`
+
+Returns `{ data, loading, error, refetch, isStale }`.
+
+- For **duckdb** / **kv**, backed by TanStack `useQuery`. Subscribes to every `invalidatedBy` pattern on mount and invalidates its own cache when a match fires.
+- For **rxdb**, subscribes to the observable via `useEffect`. `refetch()` is a no-op — the stream drives updates. Zod-parses on every emission; parse failure surfaces as `error`.
+- Cache defaults: `staleTime = 30_000`, `gcTime = 300_000`, both overridable in the query definition.
+
+### `useAppMutation<Input, Output>(name)`
+
+Returns `{ mutate, mutateAsync, loading, error, data, reset }`. On success, emits every entry in `invalidates` on the bus. On failure, clears optimistic state so subsequent renders see `data === undefined`.
+
+### `useAppEvent<TPayload>(name, handler)`
+
+Subscribes to exact-match `name`. Handler ref stays fresh across renders. Unsubscribes on unmount. For glob semantics, call `bus.subscribePattern` directly via `useDataAccessRuntime`.
+
+### `useRequestContext(): RequestContext`
+
+Reads the provider's `context()` callback on every render, so session updates propagate without remount.
+
+### `DataAccessProvider`
+
+```ts
+interface DataAccessProviderConfig {
+  registry: Registry;
+  engines: { duckdb?: DuckdbEngine; rxdb?: RxdbEngine; kv?: KvEngine };
+  context: () => RequestContext;
+  bus?: EventBus;             // optional; one is minted per provider
+  queryClient?: QueryClient;  // optional; one is minted per provider
+}
+```
+
+Nesting providers is not supported in v0.1 — mount exactly one at the app root.
+
+### `createEventBus(): EventBus`
+
+Standalone factory for tests or non-React callers. Exposes `emit`, `subscribe`, `subscribePattern`. Pattern semantics:
+
+- `hrv:*` — matches one `:`-delimited segment.
+- `hrv:**` — matches one or more segments.
+- Empty pattern rejected. Case-sensitive.
+
+### Errors
+
+- `DataAccessError` — base class with `.code`. Codes: `engine_missing`, `zod_parse_failed`, `authorization_denied`, `not_implemented`.
+- `AuthorizationError` extends `DataAccessError` (`code: 'authorization_denied'`).
+- `NotImplementedError` extends `DataAccessError` (`code: 'not_implemented'`); reserved for stubs.
+
+## ESLint plugin
+
+Blocks direct storage-engine imports outside the registry directory.
+
+```js
+// eslint.config.mjs
+import dataAccessPlugin from '@mongrov/data-access/eslint';
+
+export default [
+  {
+    plugins: { '@mongrov/data-access': dataAccessPlugin },
+    rules: {
+      '@mongrov/data-access/no-storage-engine-imports': ['error', {
+        allowedDirs: ['src/data'],
+      }],
+    },
+  },
+];
+```
+
+- Default block list: `@mongrov/analytics`, `@mongrov/collab`, `@mongrov/db` (subpaths included — `@mongrov/db/kv` is blocked by the same rule).
+- `allowedDirs` — path fragments that suppress the rule; the registry directory typically goes here.
+- `blockedPackages` — override the default block list.
+- Covers `import`, dynamic `import()`, and CommonJS `require()`.
+
+## Testing patterns
+
+The package ships with a full vitest suite you can mirror in-app.
+
+- **In-memory event bus** — `createEventBus()` is standalone and needs no engine wiring.
+- **Fake DuckDB engine** — implement `DuckdbEngine.execute(sql, params)` in a couple of lines to drive query tests.
+- **Fake RxDB observable** — a `{ subscribe(observer) }` object with `next` / `error` is enough for `useAppQuery('name.rxdb', ...)`.
+- **QueryClient with `retry: false`** — avoid retry timeouts in error-surface tests:
+
+  ```ts
+  const client = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: 0 },
+      mutations: { retry: false },
+    },
+  });
+  ```
+
+See `src/__tests__/integration.test.tsx` for a full smoke test wiring registry + provider + hooks together.
+
+## Version
+
+`0.1.0-alpha.0` — first cut. Follow-ups tracked in [`.specifica/features/data-access/tasks.md`](../../../.specifica/features/data-access/tasks.md):
+
+- Row-level invalidation
+- Streaming query results
+- Persistent cache (AsyncStorage / MMKV)
+- Devtools panel
+- Custom engine adapters (GraphQL, REST)
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,56 @@
+/**
+ * DataAccessProvider (T-16) + internal context.
+ *
+ * The provider is the single injection point for the registry, engine
+ * adapters, RequestContext factory, event bus, and TanStack QueryClient.
+ * If no bus / queryClient is supplied, one is created lazily and shared
+ * across the entire tree.
+ *
+ * See data-access/spec.md §Registry pattern.
+ */
+import { QueryClient } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+import * as React from 'react';
+import type { EngineAdapters } from './dispatcher';
+import type { EventBus, Registry, RequestContext } from './types';
+/**
+ * Concrete provider props. Diverges from DataAccessProviderProps in
+ * ./types (which stays engine-agnostic to avoid a circular import) by
+ * accepting a strongly typed EngineAdapters bundle.
+ */
+export interface DataAccessProviderConfig {
+    registry: Registry;
+    engines: EngineAdapters;
+    context: () => RequestContext;
+    /**
+     * Optional override — when omitted the provider mints its own bus.
+     * Sharing a bus across nested providers is a v0.2.0 concern.
+     */
+    bus?: EventBus;
+    /**
+     * Optional override — when omitted the provider mints its own
+     * QueryClient with default options. Supply your own to share a
+     * client across nested trees or to configure retry/staleTime.
+     */
+    queryClient?: QueryClient;
+    children?: ReactNode;
+}
+/**
+ * Runtime shape exposed via context. Kept internal so app code goes
+ * through hooks (useRequestContext / useAppEvent / …) — no direct
+ * consumers of the context value.
+ */
+export interface DataAccessRuntime {
+    registry: Registry;
+    engines: EngineAdapters;
+    bus: EventBus;
+    queryClient: QueryClient;
+    getContext: () => RequestContext;
+}
+export declare function DataAccessProvider(props: DataAccessProviderConfig): React.ReactElement;
+/**
+ * Internal — used by every hook to reach the runtime. Throws a typed
+ * error when a hook is used outside a DataAccessProvider.
+ */
+export declare function useDataAccessRuntime(): DataAccessRuntime;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAuB,MAAM,uBAAuB,CAAA;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,KAAK,EACV,QAAQ,EACR,QAAQ,EACR,cAAc,EACf,MAAM,SAAS,CAAA;AAEhB;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,QAAQ,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,cAAc,CAAA;IAC7B;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;IACvB,GAAG,EAAE,QAAQ,CAAA;IACb,WAAW,EAAE,WAAW,CAAA;IACxB,UAAU,EAAE,MAAM,cAAc,CAAA;CACjC;AAMD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,wBAAwB,GAC9B,KAAK,CAAC,YAAY,CAyCpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CASxD"}

package/dist/context.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * DataAccessProvider (T-16) + internal context.
+ *
+ * The provider is the single injection point for the registry, engine
+ * adapters, RequestContext factory, event bus, and TanStack QueryClient.
+ * If no bus / queryClient is supplied, one is created lazily and shared
+ * across the entire tree.
+ *
+ * See data-access/spec.md §Registry pattern.
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import * as React from 'react';
+import { DataAccessError } from './errors';
+import { createEventBus } from './invalidation';
+const DataAccessContext = React.createContext(null);
+DataAccessContext.displayName = 'DataAccessContext';
+export function DataAccessProvider(props) {
+    const { registry, engines, context, bus: suppliedBus, queryClient: suppliedClient, children, } = props;
+    // Bus / client are created once per provider mount. Deliberately not
+    // memoized on the supplied identity — swapping either mid-lifetime is
+    // unsupported.
+    const busRef = React.useRef(null);
+    if (busRef.current === null) {
+        busRef.current = suppliedBus ?? createEventBus();
+    }
+    const clientRef = React.useRef(null);
+    if (clientRef.current === null) {
+        clientRef.current = suppliedClient ?? new QueryClient();
+    }
+    const runtime = React.useMemo(() => ({
+        registry,
+        engines,
+        bus: busRef.current,
+        queryClient: clientRef.current,
+        getContext: context,
+    }), [registry, engines, context]);
+    return (_jsx(DataAccessContext.Provider, { value: runtime, children: _jsx(QueryClientProvider, { client: runtime.queryClient, children: children }) }));
+}
+/**
+ * Internal — used by every hook to reach the runtime. Throws a typed
+ * error when a hook is used outside a DataAccessProvider.
+ */
+export function useDataAccessRuntime() {
+    const runtime = React.useContext(DataAccessContext);
+    if (runtime === null) {
+        throw new DataAccessError('engine_missing', 'data-access hook called outside <DataAccessProvider>');
+    }
+    return runtime;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAExE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AA2C/C,MAAM,iBAAiB,GAAG,KAAK,CAAC,aAAa,CAA2B,IAAI,CAAC,CAAA;AAE7E,iBAAiB,CAAC,WAAW,GAAG,mBAAmB,CAAA;AAEnD,MAAM,UAAU,kBAAkB,CAChC,KAA+B;IAE/B,MAAM,EACJ,QAAQ,EACR,OAAO,EACP,OAAO,EACP,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,cAAc,EAC3B,QAAQ,GACT,GAAG,KAAK,CAAA;IAET,qEAAqE;IACrE,sEAAsE;IACtE,eAAe;IACf,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAkB,IAAI,CAAC,CAAA;IAClD,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC5B,MAAM,CAAC,OAAO,GAAG,WAAW,IAAI,cAAc,EAAE,CAAA;IAClD,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAqB,IAAI,CAAC,CAAA;IACxD,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC/B,SAAS,CAAC,OAAO,GAAG,cAAc,IAAI,IAAI,WAAW,EAAE,CAAA;IACzD,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAC3B,GAAG,EAAE,CAAC,CAAC;QACL,QAAQ;QACR,OAAO;QACP,GAAG,EAAE,MAAM,CAAC,OAAmB;QAC/B,WAAW,EAAE,SAAS,CAAC,OAAsB;QAC7C,UAAU,EAAE,OAAO;KACpB,CAAC,EACF,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAC7B,CAAA;IAED,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YACxC,KAAC,mBAAmB,IAAC,MAAM,EAAE,OAAO,CAAC,WAAW,YAC7C,QAAQ,GACW,GACK,CAC9B,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAA;IACnD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,sDAAsD,CACvD,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/define.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Registry primitives — defineQuery / defineMutation / defineEvent.
+ *
+ * The Define API is entirely local: no engine access, no React, no
+ * dispatcher. It hands back typed, discriminated handles that the
+ * dispatcher (arriving in a later task) can safely inspect and route.
+ *
+ * See data-access/spec.md §Define API.
+ */
+import type { EventDefinition, MutationConfig, MutationDefinition, QueryConfig, QueryDefinition } from './types';
+/**
+ * Register a typed query. Runtime enforces the engine-specific required
+ * field so JS callers get a loud error even when TypeScript is skipped.
+ */
+export declare function defineQuery<TInput, TOutput>(config: QueryConfig<TInput, TOutput>): QueryDefinition<TInput, TOutput>;
+/**
+ * Register a typed mutation. `exec` is required; `invalidates` patterns
+ * fire through the invalidation bus on success.
+ */
+export declare function defineMutation<TInput, TOutput>(config: MutationConfig<TInput, TOutput>): MutationDefinition<TInput, TOutput>;
+/**
+ * Register a typed event. Payload type is inferred at the point of use
+ * (via useAppEvent). No runtime state is captured here.
+ */
+export declare function defineEvent<TPayload>(): EventDefinition<TPayload>;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,eAAe,EAChB,MAAM,SAAS,CAAA;AAEhB;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EACzC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAGlC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAC5C,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAQrC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,KAAK,eAAe,CAAC,QAAQ,CAAC,CAEjE"}

package/dist/define.js

@@ -0,0 +1,60 @@
+/**
+ * Registry primitives — defineQuery / defineMutation / defineEvent.
+ *
+ * The Define API is entirely local: no engine access, no React, no
+ * dispatcher. It hands back typed, discriminated handles that the
+ * dispatcher (arriving in a later task) can safely inspect and route.
+ *
+ * See data-access/spec.md §Define API.
+ */
+import { DataAccessError } from './errors';
+/**
+ * Register a typed query. Runtime enforces the engine-specific required
+ * field so JS callers get a loud error even when TypeScript is skipped.
+ */
+export function defineQuery(config) {
+    assertQueryEngineField(config);
+    return { __kind: 'query', config };
+}
+/**
+ * Register a typed mutation. `exec` is required; `invalidates` patterns
+ * fire through the invalidation bus on success.
+ */
+export function defineMutation(config) {
+    if (typeof config.exec !== 'function') {
+        throw new DataAccessError('define_config_invalid', 'defineMutation requires an `exec` function');
+    }
+    return { __kind: 'mutation', config };
+}
+/**
+ * Register a typed event. Payload type is inferred at the point of use
+ * (via useAppEvent). No runtime state is captured here.
+ */
+export function defineEvent() {
+    return { __kind: 'event' };
+}
+function assertQueryEngineField(config) {
+    switch (config.engine) {
+        case 'duckdb':
+            if (typeof config.sql !== 'string' || config.sql.length === 0) {
+                throw new DataAccessError('define_config_invalid', "defineQuery: engine 'duckdb' requires a non-empty `sql` string");
+            }
+            return;
+        case 'rxdb':
+            if (typeof config.query !== 'function') {
+                throw new DataAccessError('define_config_invalid', "defineQuery: engine 'rxdb' requires a `query` function");
+            }
+            return;
+        case 'kv':
+            if (typeof config.keyBuilder !== 'function') {
+                throw new DataAccessError('define_config_invalid', "defineQuery: engine 'kv' requires a `keyBuilder` function");
+            }
+            return;
+        default: {
+            // Exhaustiveness: if a new engine is added, TS surfaces this at compile time.
+            const exhaustive = config;
+            throw new DataAccessError('define_config_invalid', `defineQuery: unknown engine ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAS1C;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,MAAoC;IAEpC,sBAAsB,CAAC,MAAM,CAAC,CAAA;IAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAuC;IAEvC,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,eAAe,CACvB,uBAAuB,EACvB,4CAA4C,CAC7C,CAAA;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAA;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;AAC5B,CAAC;AAED,SAAS,sBAAsB,CAC7B,MAAoC;IAEpC,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,QAAQ;YACX,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,eAAe,CACvB,uBAAuB,EACvB,gEAAgE,CACjE,CAAA;YACH,CAAC;YACD,OAAM;QACR,KAAK,MAAM;YACT,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACvC,MAAM,IAAI,eAAe,CACvB,uBAAuB,EACvB,wDAAwD,CACzD,CAAA;YACH,CAAC;YACD,OAAM;QACR,KAAK,IAAI;YACP,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;gBAC5C,MAAM,IAAI,eAAe,CACvB,uBAAuB,EACvB,2DAA2D,CAC5D,CAAA;YACH,CAAC;YACD,OAAM;QACR,OAAO,CAAC,CAAC,CAAC;YACR,8EAA8E;YAC9E,MAAM,UAAU,GAAU,MAAM,CAAA;YAChC,MAAM,IAAI,eAAe,CACvB,uBAAuB,EACvB,+BAA+B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAC5D,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/dispatcher.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Engine dispatcher (T-06 · T-07 · T-08).
+ *
+ * `executeQuery` resolves a registered query definition against a set of
+ * engine adapters and returns typed output. This is the read-path used
+ * both by useAppQuery (arriving in a later task) and by direct callers
+ * that want dispatcher semantics without React.
+ *
+ * Concerns wired here:
+ *
+ *   - T-06 — dispatch by `def.config.engine`
+ *   - T-07 — run `authorize` gate before execution
+ *   - T-08 — merge tenant pair into DuckDB params
+ *
+ * Engines are provided as adapter objects (see EngineAdapters below).
+ * The dispatcher never imports @mongrov/analytics or @mongrov/db.
+ */
+import type { QueryDefinition, RequestContext, RxdbQueryConfig } from './types';
+/**
+ * DuckDB adapter — analytics engine surface consumed by the dispatcher.
+ */
+export interface DuckdbEngine {
+    execute(sql: string, params: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * RxDB adapter — the app-provided runner takes the raw QueryConfig and
+ * caller input, executes `config.query(db, input)`, converts the returned
+ * Observable to a promise (`firstValueFrom`), and yields the first value.
+ *
+ * This keeps rxjs out of the data-access peer graph — the adapter is
+ * responsible for the rxjs boundary.
+ */
+export interface RxdbEngine {
+    db: unknown;
+    execute<TInput>(config: RxdbQueryConfig<TInput, unknown>, input: TInput): Promise<unknown>;
+}
+/**
+ * KV adapter — the dispatcher builds the key via `config.keyBuilder(input)`
+ * and reads through the app-provided store.
+ */
+export interface KvEngine {
+    get(key: string): Promise<unknown> | unknown;
+}
+/**
+ * Concrete engine bundle. Any subset may be omitted; the dispatcher
+ * throws `engine_missing` if a query targets an omitted engine.
+ */
+export interface EngineAdapters {
+    duckdb?: DuckdbEngine;
+    rxdb?: RxdbEngine;
+    kv?: KvEngine;
+}
+/**
+ * T-06 core — resolve a registered query and return typed output.
+ */
+export declare function executeQuery<TInput, TOutput>(def: QueryDefinition<TInput, TOutput>, input: TInput, ctx: RequestContext, engines: EngineAdapters): Promise<TOutput>;
+/**
+ * T-07 — authorization gate. Runs the definition's `authorize` if
+ * present; a `false` result throws `AuthorizationError`.
+ */
+export declare function runAuthorize<TInput>(authorize: ((input: TInput, ctx: RequestContext) => boolean | Promise<boolean>) | undefined, input: TInput, ctx: RequestContext): Promise<void>;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../src/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,OAAO,KAAK,EAGV,eAAe,EACf,cAAc,EACd,eAAe,EAChB,MAAM,SAAS,CAAA;AAEhB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,MAAM,EACZ,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,EAAE,CAAC,EAAE,QAAQ,CAAA;CACd;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,OAAO,EAChD,GAAG,EAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAQlB;AAiCD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,MAAM,EACvC,SAAS,EACL,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GACpE,SAAS,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/dispatcher.js

@@ -0,0 +1,91 @@
+/**
+ * Engine dispatcher (T-06 · T-07 · T-08).
+ *
+ * `executeQuery` resolves a registered query definition against a set of
+ * engine adapters and returns typed output. This is the read-path used
+ * both by useAppQuery (arriving in a later task) and by direct callers
+ * that want dispatcher semantics without React.
+ *
+ * Concerns wired here:
+ *
+ *   - T-06 — dispatch by `def.config.engine`
+ *   - T-07 — run `authorize` gate before execution
+ *   - T-08 — merge tenant pair into DuckDB params
+ *
+ * Engines are provided as adapter objects (see EngineAdapters below).
+ * The dispatcher never imports @mongrov/analytics or @mongrov/db.
+ */
+import { AuthorizationError, DataAccessError, } from './errors';
+import { mergeTenantParams } from './tenant';
+/**
+ * T-06 core — resolve a registered query and return typed output.
+ */
+export async function executeQuery(def, input, ctx, engines) {
+    const parsedInput = parseInput(def.config.input, input);
+    await runAuthorize(def.config.authorize, parsedInput, ctx);
+    const raw = await dispatchByEngine(def.config, parsedInput, ctx, engines);
+    return parseOutput(def.config.output, raw);
+}
+function parseInput(schema, input) {
+    if (!schema)
+        return input;
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        throw new DataAccessError('zod_parse_failed', `input failed schema validation: ${result.error.message}`, result.error);
+    }
+    return result.data;
+}
+function parseOutput(schema, raw) {
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        throw new DataAccessError('zod_parse_failed', `output failed schema validation: ${result.error.message}`, result.error);
+    }
+    return result.data;
+}
+/**
+ * T-07 — authorization gate. Runs the definition's `authorize` if
+ * present; a `false` result throws `AuthorizationError`.
+ */
+export async function runAuthorize(authorize, input, ctx) {
+    if (!authorize)
+        return;
+    const allowed = await Promise.resolve(authorize(input, ctx));
+    if (!allowed) {
+        throw new AuthorizationError('authorization denied by query authorize hook');
+    }
+}
+async function dispatchByEngine(config, input, ctx, engines) {
+    switch (config.engine) {
+        case 'duckdb':
+            return dispatchDuckdb(config, input, ctx, engines.duckdb);
+        case 'rxdb':
+            return dispatchRxdb(config, input, engines.rxdb);
+        case 'kv':
+            return dispatchKv(config, input, engines.kv);
+        default: {
+            const exhaustive = config;
+            throw new DataAccessError('engine_missing', `unknown engine: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+function dispatchDuckdb(config, input, ctx, engine) {
+    if (!engine) {
+        throw new DataAccessError('engine_missing', "engine 'duckdb' is not wired in this dispatcher");
+    }
+    const params = mergeTenantParams(input, ctx);
+    return engine.execute(config.sql, params);
+}
+function dispatchRxdb(config, input, engine) {
+    if (!engine) {
+        throw new DataAccessError('engine_missing', "engine 'rxdb' is not wired in this dispatcher");
+    }
+    return engine.execute(config, input);
+}
+async function dispatchKv(config, input, engine) {
+    if (!engine) {
+        throw new DataAccessError('engine_missing', "engine 'kv' is not wired in this dispatcher");
+    }
+    const key = config.keyBuilder(input);
+    return engine.get(key);
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../src/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EACL,kBAAkB,EAClB,eAAe,GAChB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAkD5C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAqC,EACrC,KAAa,EACb,GAAmB,EACnB,OAAuB;IAEvB,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;IAEvD,MAAM,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,CAAC,CAAA;IAE1D,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IAEzE,OAAO,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC5C,CAAC;AAED,SAAS,UAAU,CACjB,MAAqC,EACrC,KAAa;IAEb,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACzB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,mCAAmC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EACzD,MAAM,CAAC,KAAK,CACb,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAA;AACpB,CAAC;AAED,SAAS,WAAW,CAClB,MAA0B,EAC1B,GAAY;IAEZ,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IACpC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,oCAAoC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EAC1D,MAAM,CAAC,KAAK,CACb,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAA;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAEa,EACb,KAAa,EACb,GAAmB;IAEnB,IAAI,CAAC,SAAS;QAAE,OAAM;IACtB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;IAC5D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,kBAAkB,CAAC,8CAA8C,CAAC,CAAA;IAC9E,CAAC;AACH,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,MAAkD,EAClD,KAAa,EACb,GAAmB,EACnB,OAAuB;IAEvB,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,QAAQ;YACX,OAAO,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;QAC3D,KAAK,MAAM;YACT,OAAO,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;QAClD,KAAK,IAAI;YACP,OAAO,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;QAC9C,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,MAAM,CAAA;YAChC,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,mBAAmB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAChD,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CACrB,MAA0C,EAC1C,KAAa,EACb,GAAmB,EACnB,MAAgC;IAEhC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,iDAAiD,CAClD,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC5C,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC;AAED,SAAS,YAAY,CACnB,MAAwC,EACxC,KAAa,EACb,MAA8B;IAE9B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,+CAA+C,CAChD,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AACtC,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,MAAsC,EACtC,KAAa,EACb,MAA4B;IAE5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,6CAA6C,CAC9C,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IACpC,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AACxB,CAAC"}