@cratestack/refine 0.7.14 → 0.7.17

package/README.md

@@ -1,44 +1,78 @@
 # @cratestack/refine
 
-A [refine.dev](https://refine.dev) `DataProvider` over CrateStack's generated TypeScript **REST**
-client. Wires refine's fixed `getList`/`getOne`/`getMany`/`create`/`update`/`deleteOne` surface to
-a generated model class (`client.widgets`, `client.ledgers`, …), mapping refine's filter operators,
-pagination, primary keys, and `@version` optimistic-locking conflicts onto the server's real
-contract — the same one [cratestack-studio](https://cratestack.dev) deliberately bypasses.
-`cratestack-studio` talks to `[target.db]` directly and skips `@@allow`; a refine app built on this
-package goes through the generated API and inherits policy, validation, `@version` concurrency, and
-audit. That's the reason this package exists (cratestack#571): refine is the safe end-user admin
-surface, Studio is the sysadmin one.
-
-This package covers REST-transport schemas only (`generate-typescript`'s default transport, no
-`transport rpc`) — see [Scope](#scope) below.
-
-## Why a runtime package, not a generator
-
-The open question cratestack#571 asked to settle first: how much of this genuinely has to be
-generated per schema? Answer: none of it, given a small hand-written manifest.
-
-A `DataProvider` needs three schema facts per resource — its primary-key field name, whether its
-model declares `@@paged`, and whether/where it declares `@version` — plus the resource's own
-generated API object. None of those four things has a runtime discovery path: the generated client
-carries no `$meta` object, no introspection endpoint, nothing beyond what its TypeScript *types*
-already encode at compile time (confirmed by reading the real generated `client.ts`/`models.ts`
-output this package's own tests drive — see [tests/](./tests)). Whether or not `@cratestack/refine`
-ships a code generator, an app still needs to write down those four things per resource somewhere.
-A generator that emits a five-line object literal isn't materially cheaper to maintain than writing
-that object literal directly against the schema the developer already wrote — it's a second
-artifact to keep in sync instead of one. So this package is exactly what `createCratestackDataProvider`
-below is: a hand-written runtime function over a hand-written manifest, no `cratestack generate-*`
-subcommand, no build step beyond `tsc`.
-
-## Usage
+A [refine.dev](https://refine.dev) `DataProvider` over CrateStack's generated TypeScript client —
+**REST** (`createCratestackDataProvider`) or **RPC** (`createCratestackRpcDataProvider`, for
+`transport rpc` schemas). Wires refine's fixed `getList`/`getOne`/`getMany`/`create`/`update`/
+`deleteOne` surface to a generated model class (`client.widgets`, `client.ledgers`, …), mapping
+refine's filter operators, pagination, primary keys, and `@version` optimistic-locking conflicts
+onto the server's real contract — the same one [cratestack-studio](https://cratestack.dev)
+deliberately bypasses. `cratestack-studio` talks to `[target.db]` directly and skips `@@allow`; a
+refine app built on this package goes through the generated API and inherits policy, validation,
+`@version` concurrency, and audit. That's the reason this package exists (cratestack#571): refine
+is the safe end-user admin surface, Studio is the sysadmin one.
+
+Both transports share this same README except where a section says otherwise — the two providers'
+`getList`/`getOne`/`getMany`/`create`/`update`/`deleteOne`/`createMany`/`updateMany`/`deleteMany`/
+`custom` behavior, filter-operator table, pagination semantics, primary-key handling, and `@version`
+optimistic-locking guarantee are identical; only the wire calls underneath differ. See
+[RPC transport](#rpc-transport) below for what's RPC-specific, and [Scope](#scope) for what neither
+provider does.
+
+## A runtime package with a generated manifest
+
+A `DataProvider` needs four things per resource — the generated API object itself, the model's
+primary-key field name, whether it declares `@@paged`, and whether/where it declares `@version`.
+None of them has a *runtime* discovery path: the generated client carries no `$meta` object and no
+introspection endpoint, nothing beyond what its TypeScript **types** already encode at compile time
+(confirmed against the real generated `client.ts`/`models.ts` this package's own tests drive — see
+[tests/](./tests)). So the provider itself has to be a hand-written runtime function; there is
+nothing schema-shaped in its logic to generate.
+
+The **manifest** is a different question, and cratestack#571 settled it the other way: those four
+facts all live in the `.cstack` schema, so the generator emits them. Pass `--refine` to
+`cratestack generate-typescript` and it writes an extra `src/refine.ts` next to the client:
+
+```bash
+cratestack generate-typescript \
+  --schema schema.cstack \
+  --out ./generated \
+  --refine
+```
+
+```ts
+// generated/src/refine.ts — generated, do not edit
+export function cratestackRefineResources(client: ExampleApiClientClient): ResourceMap { … }
+```
+
+Writing that manifest by hand is still perfectly supported (it is a plain object literal, and every
+example below shows one), but the generated one cannot drift: a model that gains `@version`, or one
+whose `@id` is not called `id`, updates itself on the next `generate-typescript` run instead of
+failing quietly at runtime.
+
+`--refine` works for **both** REST and RPC schemas. The emitted function is the same shape either
+way — `cratestackRefineResources(client)` — typed `ResourceMap` for REST and `RpcResourceMap` for
+RPC, so consumer code is identical across transports. Only `transport grpc` is rejected
+(`TypeScriptGeneratorError::RefineRequiresRestOrRpc`): its client speaks typed protobuf with no
+URL-query shaping, so there is nothing for this provider to drive. It also composes freely with
+`--swr` (the file-per-model + hooks layout, `<package-name>/swr`): the manifest binds to the
+always-emitted default layout's client class regardless of that flag. See [Scope](#scope).
+
+## Usage (REST)
+
+With the generated manifest:
 
 ```ts
 import { createCratestackDataProvider } from "@cratestack/refine";
-import { ExampleApiClientClient } from "./generated/client"; // your project's generated REST client
+import { ExampleApiClientClient } from "./generated/src/client.js";
+import { cratestackRefineResources } from "./generated/src/refine.js";
 
 const client = new ExampleApiClientClient("https://api.example.com", { basePath: "/api" });
+const dataProvider = createCratestackDataProvider(cratestackRefineResources(client));
+```
 
+Or writing the manifest yourself — identical shape, and what the generated file contains:
+
+```ts
 const dataProvider = createCratestackDataProvider({
   widgets: { api: client.widgets, primaryKey: "id", paged: false },
   ledgers: { api: client.ledgers, primaryKey: "id", paged: true, versionField: "version" },
@@ -48,10 +82,59 @@ const dataProvider = createCratestackDataProvider({
 
 Pass this straight to refine's `<Refine dataProvider={dataProvider} .../>`.
 
+## RPC transport
+
+For a `transport rpc` schema, use `createCratestackRpcDataProvider` and an `RpcResourceMap` instead
+— same four facts per resource (`api`, `primaryKey`, `paged`, optional `versionField`), same
+`getList`/`getOne`/.../`custom` behavior, same filter-operator table and `@version` guarantee as
+REST. There is no generated manifest for RPC yet (`--refine` rejects RPC schemas — see above), so
+write it by hand:
+
+```ts
+import { createCratestackRpcDataProvider } from "@cratestack/refine";
+import { ExampleApiClientClient } from "./generated/src/client.js";
+
+const client = new ExampleApiClientClient("https://api.example.com", { basePath: "/api" });
+const dataProvider = createCratestackRpcDataProvider({
+  widgets: { api: client.widgets, primaryKey: "id", paged: false },
+  ledgers: { api: client.ledgers, primaryKey: "id", paged: true, versionField: "version" },
+  products: { api: client.products, primaryKey: "sku", paged: false },
+});
+```
+
+What's different from REST, mechanically:
+
+- The generated RPC model class's `list` takes its query positionally
+  (`list(query, options)`) instead of nested in an options object the way REST's `list({ query,
+  headers, signal })` does — `createCratestackRpcDataProvider` builds an `RpcListQuery` (RPC's typed
+  list-input shape) instead of REST's `CratestackFetchQuery`. `get`/`create`/`update`/`delete` are
+  positionally identical between the two transports; only their options type differs
+  (`CratestackRpcCallOptions` vs `CratestackRequestConfig`).
+- Filters compile to `RpcListPredicate[]` (`{ key, value }` pairs) instead of REST's
+  `Record<string,string>` — same `field[__operator]` key convention either way (see
+  [Filters](#filters) below), just a different container shape on the wire.
+- Sort compiles to a single comma-joined string (`"-createdAt,id"`) instead of REST's `string[]`
+  the runtime joins client-side — same `field`/`-field` DSL.
+- **Every unary call carries `If-Match` exactly like REST does.** The RPC dispatch arms
+  (`crates/cratestack-macros/src/transport/rpc.rs`) pass the real HTTP `HeaderMap` straight through
+  to the identical `handle_update_*_dispatch`/`handle_delete_*_dispatch` fns REST uses
+  (`crates/cratestack-macros/src/axum/model/handlers_update.rs`), which read `If-Match` via
+  `parse_if_match_version` — so a stale or missing `If-Match` against a `@version` model returns the
+  same `412 Precondition Failed` on both transports, verified against a real generated RPC client in
+  this package's own test suite (`tests/rpc-optimistic-locking.test.ts`).
+- **`createCratestackRpcDataProvider` never calls `POST /rpc/batch`.** A batch request is one HTTP
+  request carrying N frames, so a per-frame `If-Match` header isn't expressible there —
+  `createMany`/`updateMany`/`deleteMany` are N real unary round trips instead, same non-atomic
+  strategy REST uses (see [createMany / updateMany / deleteMany](#createmany--updatemany--deletemany)
+  below). A batched RPC data provider is possible in principle but out of scope here — see
+  [Scope](#scope).
+
 ## Filters
 
-refine's `CrudFilters` (`{ field, operator, value }`) map onto the generated list route's
-`field__operator=value` query convention — the same operator set the generated client's shared
+Applies to both providers. refine's `CrudFilters` (`{ field, operator, value }`) map onto the same
+`field[__operator]` key convention on both transports — REST's `field__operator=value` query params
+(`toQueryFilters`) and RPC's `RpcListPredicate[]` (`toRpcQueryFilters`) carry an identical `key`,
+just in different container shapes on the wire. Same operator set the generated client's shared
 filter types (`EqualityFilter`/`ComparableFilter`/`StringFilter`) expose:
 
 | refine operator | cratestack query key |
@@ -75,7 +158,8 @@ package can work around.
 
 ## Pagination
 
-refine's `{ current, pageSize }` maps to `limit`/`offset` directly. **`totalCount` is only ever
+Applies to both providers. refine's `{ current, pageSize }` maps to `limit`/`offset` directly.
+**`totalCount` is only ever
 emitted for a `@@paged` model's list route.** Set `paged: false` in a resource's config honestly —
 a non-`@@paged` resource's `getList` still returns real data, but `total` degrades to
 "how many rows this one response returned" rather than a true count. Either add `@@paged` to the
@@ -84,7 +168,7 @@ one (capped) page.
 
 ## Primary keys
 
-refine assumes every record has `id: BaseKey`. cratestack's `@id` can be on any field
+Applies to both providers. refine assumes every record has `id: BaseKey`. cratestack's `@id` can be on any field
 (`primaryKey` in the resource config above). Every returned record gets a synthetic `id` field
 alongside its real primary key so refine's row-selection machinery has something to key off;
 writes (`get`/`update`/`deleteOne`) receive that same value back and pass it straight through as
@@ -94,12 +178,15 @@ this bites: a `<Create>` form's fields must use the schema's real primary-key fi
 
 ## Optimistic locking (`@version` / `If-Match`)
 
-**The single most important correctness point in this package.** A `@version` model requires
-`If-Match` on both update *and* delete (cratestack#493/#519/#538) — missing or stale `If-Match`
-returns `412 Precondition Failed` and leaves the row untouched. refine's `update`/`deleteOne` hooks
-fetch the record before editing it, so the version is known by the time a mutation fires; this
-package remembers it (keyed per `createCratestackDataProvider` call, not module-global) from every
-read/write that returns a fresh record, and sends it automatically. A `412` is surfaced as a
+**The single most important correctness point in this package, and it holds on both transports.**
+A `@version` model requires `If-Match` on both update *and* delete (cratestack#493/#519/#538) —
+missing or stale `If-Match` returns `412 Precondition Failed` and leaves the row untouched, whether
+the request went out as an RPC unary call or a REST `PATCH`/`DELETE` (see
+[RPC transport](#rpc-transport) for why the RPC dispatch path enforces this identically to REST).
+refine's `update`/`deleteOne` hooks fetch the record before editing it, so the version is known by
+the time a mutation fires; each provider remembers it (keyed per `createCratestackDataProvider`/
+`createCratestackRpcDataProvider` call, not module-global) from every read/write that returns a
+fresh record, and sends it automatically. A `412` is surfaced as a
 distinguishable conflict (`statusCode: 412`, a human-readable message) rather than a generic
 failure — check `error.statusCode === 412` in an `onError` handler to show a "someone else changed
 this" message instead of a generic one.
@@ -111,16 +198,20 @@ fail on the wire the way a *stale* value does, so this package refuses to make t
 
 ## `createMany` / `updateMany` / `deleteMany`
 
-Implemented, not declined — but as N sequential single-record round trips (`Promise.all` over
-`create`/`update`/`deleteOne`), not a real batch. The generated REST client exposes no
-`updateMany`/`deleteMany` wrapper around the server's actual `update_many`/`delete_many`, and
-`/rpc/batch` is an RPC-transport-only endpoint. So these three methods work, but without atomicity
-and at the cost of N requests instead of one.
+Implemented, not declined, on both providers — but as N sequential single-record round trips
+(`Promise.all` over `create`/`update`/`deleteOne`), not a real batch. The generated REST client
+exposes no `updateMany`/`deleteMany` wrapper around the server's actual `update_many`/
+`delete_many`. The RPC transport does have a real batch endpoint (`POST /rpc/batch`), but
+`createCratestackRpcDataProvider` deliberately doesn't use it here either — see
+[RPC transport](#rpc-transport) for why (per-frame `If-Match` isn't expressible in a batch request).
+So these three methods work on both transports, but without atomicity and at the cost of N requests
+instead of one.
 
 ## Procedures (`custom`)
 
 A cratestack `procedure` has no other home in a `DataProvider`. Pass a `procedures` map to
-`createCratestackDataProvider`'s second argument and call it through refine's `custom`:
+`createCratestackDataProvider`'s (or `createCratestackRpcDataProvider`'s) second argument and call
+it through refine's `custom` — identical shape on both providers:
 
 ```ts
 const dataProvider = createCratestackDataProvider(resources, {
@@ -141,10 +232,17 @@ await dataProvider.custom!({
 
 - **`liveProvider`** — the generated TypeScript client has no SSE consumer today (no `EventSource`
   anywhere in `crates/cratestack-client-typescript/templates/`), even though the server has a real
-  subscribe endpoint. Needs a TS SSE client first.
-- **`authProvider`** — a separate, orthogonal concern from data access.
-- **RPC-transport schemas** (`transport rpc`) — this package's filter/pagination query-string
-  convention is REST-specific. An RPC dataProvider needs its own mapping layer.
+  subscribe endpoint. Needs a TS SSE client first. Applies to both transports.
+- **`authProvider`** — a separate, orthogonal concern from data access. Applies to both transports.
+- **Batched RPC writes** — `createCratestackRpcDataProvider` never calls `POST /rpc/batch`, even
+  though the RPC transport has one. A per-frame `If-Match` header isn't expressible in a single
+  batch request, and this package's `@version` guarantee is not something it will silently weaken
+  to get atomicity — see [RPC transport](#rpc-transport).
+- **RPC's `where`/`or` filter-expression DSL, and `fields`/`include`/`includeFields` projection** —
+  `CratestackRpcListQuery` supports all of these on the wire, but refine's `CrudFilters`/`Sort`
+  shapes have nothing that maps onto them (refine has no "raw server filter expression" or
+  "relation projection" concept), so this provider never writes to them. Available to a caller who
+  wants to reach past refine's abstraction: call `config.api.list({ where: "..." })` directly.
 
 **A known, pre-existing gap this package inherits rather than causes:** route suppression
 (cratestack#514) isn't implemented, so a policy-denied `create`/`update`/`delete` still generates a

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+import type { HttpError } from "@refinedev/core";
+import type { CratestackHttpErrorLike } from "./types.js";
+/** Structural check for the generated client's `CratestackHttpError`
+ *  (`crates/cratestack-client-typescript/templates/src/rest-runtime.ts.j2`)
+ *  — `instanceof` doesn't work here because that class is regenerated
+ *  per consumer into their own package, so this package has no shared
+ *  class reference to check against. `status` is set unconditionally by
+ *  the runtime's `!response.ok` branch regardless of codec, which makes
+ *  it the more robust field to key on than pattern-matching the error
+ *  envelope's `payload.code`. */
+export declare function isCratestackHttpError(error: unknown): error is CratestackHttpErrorLike;
+/** Converts a thrown error from a generated model API call into refine's
+ *  `HttpError`. A `412 Precondition Failed` — the response an
+ *  `If-Match`-guarded update/delete returns on a stale version — is
+ *  surfaced as a distinguishable conflict (`statusCode: 412` with a
+ *  human-readable message) rather than folded into a generic failure;
+ *  this is the one piece of information a refine UI needs to tell "your
+ *  edit was rejected because someone else changed this record first"
+ *  apart from every other kind of failure. */
+export declare function toRefineError(error: unknown): HttpError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;iCAOiC;AACjC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAOtF;AAED;;;;;;;8CAO8C;AAC9C,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAevD"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+/** Structural check for the generated client's `CratestackHttpError`
+ *  (`crates/cratestack-client-typescript/templates/src/rest-runtime.ts.j2`)
+ *  — `instanceof` doesn't work here because that class is regenerated
+ *  per consumer into their own package, so this package has no shared
+ *  class reference to check against. `status` is set unconditionally by
+ *  the runtime's `!response.ok` branch regardless of codec, which makes
+ *  it the more robust field to key on than pattern-matching the error
+ *  envelope's `payload.code`. */
+export function isCratestackHttpError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "status" in error &&
+        typeof error.status === "number");
+}
+/** Converts a thrown error from a generated model API call into refine's
+ *  `HttpError`. A `412 Precondition Failed` — the response an
+ *  `If-Match`-guarded update/delete returns on a stale version — is
+ *  surfaced as a distinguishable conflict (`statusCode: 412` with a
+ *  human-readable message) rather than folded into a generic failure;
+ *  this is the one piece of information a refine UI needs to tell "your
+ *  edit was rejected because someone else changed this record first"
+ *  apart from every other kind of failure. */
+export function toRefineError(error) {
+    if (isCratestackHttpError(error)) {
+        if (error.status === 412) {
+            return {
+                message: "This record changed since it was loaded. Reload it and try again.",
+                statusCode: 412,
+            };
+        }
+        const payload = error.payload;
+        return {
+            message: payload?.message ?? error.message ?? "Request failed",
+            statusCode: error.status,
+        };
+    }
+    return { message: error instanceof Error ? error.message : "Unknown error", statusCode: 500 };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;iCAOiC;AACjC,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,QAAQ,IAAI,KAAK;QACjB,OAAQ,KAA6B,CAAC,MAAM,KAAK,QAAQ,CAC1D,CAAC;AACJ,CAAC;AAED;;;;;;;8CAO8C;AAC9C,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACzB,OAAO;gBACL,OAAO,EAAE,mEAAmE;gBAC5E,UAAU,EAAE,GAAG;aAChB,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAA2C,CAAC;QAClE,OAAO;YACL,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,gBAAgB;YAC9D,UAAU,EAAE,KAAK,CAAC,MAAM;SACzB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AAChG,CAAC"}

package/dist/filter-operators.d.ts

@@ -0,0 +1,12 @@
+/** Returns the `field__<suffix>` query key's suffix (`null` for bare
+ *  equality), or **throws** for a refine operator with no cratestack
+ *  equivalent (`endswith`, `between`, `nin`, `containss`, …). Throwing
+ *  rather than silently dropping the filter matters: a dropped filter
+ *  would show the caller an unfiltered result set as if it were
+ *  filtered, which is worse than an error because nothing signals the
+ *  data is wrong. */
+export declare function requireOperatorSuffix(field: string, operator: string): string | null;
+/** Renders a refine filter's `value` into the string every cratestack
+ *  query key expects on the wire, for either transport. */
+export declare function filterValue(operator: string, value: unknown): string;
+//# sourceMappingURL=filter-operators.d.ts.map

package/dist/filter-operators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-operators.d.ts","sourceRoot":"","sources":["../src/filter-operators.ts"],"names":[],"mappings":"AAiCA;;;;;;qBAMqB;AACrB,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASpF;AAED;2DAC2D;AAC3D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAMpE"}

package/dist/filter-operators.js

@@ -0,0 +1,60 @@
+/** refine `CrudFilters` operator -> the generated list route's
+ *  `field__<operator>=value` query-string suffix (`null` means "no
+ *  suffix", i.e. plain equality). Shared by both transports' list-query
+ *  builders — `filters.ts` (REST, `Record<string,string>`) and
+ *  `rpc-filters.ts` (RPC, `RpcListPredicate[]`) — because the underlying
+ *  `field__op` key convention is identical on the wire: both are
+ *  generated from the same per-field arm table
+ *  (`crates/cratestack-macros/src/axum/filter_arms.rs::generate_query_filter_arm`),
+ *  confirmed by reading `crates/cratestack-axum/src/rpc/synthesize.rs`,
+ *  which turns an RPC `filters: [{key, value}]` predicate into the exact
+ *  same `key=value` query pair the REST list handler parses. Keeping this
+ *  table in ONE place is what makes "REST and RPC agree on filter
+ *  operators" a fact rather than something that can drift between two
+ *  copies. Also keep this in lockstep with `guides/refine-integration.md`
+ *  in cratestack-docs, which documents the identical mapping for
+ *  hand-wired consumers. */
+const SUPPORTED_OPERATOR_SUFFIX = {
+    eq: null,
+    ne: "ne",
+    in: "in",
+    lt: "lt",
+    lte: "lte",
+    gt: "gt",
+    gte: "gte",
+    contains: "contains",
+    startswith: "startsWith",
+    null: "isNull",
+    nnull: "isNull",
+};
+/** Every operator this map understands, for the error message below. */
+const SUPPORTED_OPERATORS = Object.keys(SUPPORTED_OPERATOR_SUFFIX);
+/** Returns the `field__<suffix>` query key's suffix (`null` for bare
+ *  equality), or **throws** for a refine operator with no cratestack
+ *  equivalent (`endswith`, `between`, `nin`, `containss`, …). Throwing
+ *  rather than silently dropping the filter matters: a dropped filter
+ *  would show the caller an unfiltered result set as if it were
+ *  filtered, which is worse than an error because nothing signals the
+ *  data is wrong. */
+export function requireOperatorSuffix(field, operator) {
+    if (!(operator in SUPPORTED_OPERATOR_SUFFIX)) {
+        throw new Error(`refine operator "${operator}" on "${field}" has no cratestack equivalent ` +
+            `(supported: ${SUPPORTED_OPERATORS.join(", ")}) — failing loudly instead of silently ` +
+            "returning unfiltered data");
+    }
+    return SUPPORTED_OPERATOR_SUFFIX[operator] ?? null;
+}
+/** Renders a refine filter's `value` into the string every cratestack
+ *  query key expects on the wire, for either transport. */
+export function filterValue(operator, value) {
+    if (operator === "null")
+        return "true";
+    if (operator === "nnull")
+        return "false";
+    if (Array.isArray(value))
+        return value.map(String).join(",");
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
+//# sourceMappingURL=filter-operators.js.map

package/dist/filter-operators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-operators.js","sourceRoot":"","sources":["../src/filter-operators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;4BAe4B;AAC5B,MAAM,yBAAyB,GAAkC;IAC/D,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,KAAK;IACV,EAAE,EAAE,IAAI;IACR,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IACxB,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,QAAQ;CAChB,CAAC;AAEF,wEAAwE;AACxE,MAAM,mBAAmB,GAAG,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;AAEnE;;;;;;qBAMqB;AACrB,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,QAAgB;IACnE,IAAI,CAAC,CAAC,QAAQ,IAAI,yBAAyB,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,oBAAoB,QAAQ,SAAS,KAAK,iCAAiC;YACzE,eAAe,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,yCAAyC;YACtF,2BAA2B,CAC9B,CAAC;IACJ,CAAC;IACD,OAAO,yBAAyB,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;AACrD,CAAC;AAED;2DAC2D;AAC3D,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,KAAc;IAC1D,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACvC,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/filters.d.ts

@@ -0,0 +1,17 @@
+import type { CrudFilters, CrudSorting } from "@refinedev/core";
+/** Converts refine's `CrudFilters` into the generated REST list route's
+ *  flat `field__operator=value` query-param convention (`RpcResourceMap`'s
+ *  sibling `toRpcQueryFilters` in `rpc-filters.ts` does the same mapping
+ *  for the RPC transport's `RpcListPredicate[]` shape — see
+ *  `filter-operators.ts` for the shared operator table both draw from).
+ *  refine operators with no cratestack equivalent — `endswith`,
+ *  `between`, `nin`, `containss`, and every refine conditional-filter
+ *  group (`or`/`and`) — **throw** rather than silently dropping the
+ *  filter: a dropped filter would show the caller an unfiltered result
+ *  set as if it were filtered, which is worse than an error because
+ *  nothing signals the data is wrong. */
+export declare function toQueryFilters(filters?: CrudFilters): Record<string, string>;
+/** refine `CrudSorting` -> the generated list route's `sort` query
+ *  values (`field` ascending, `-field` descending). */
+export declare function toSortQuery(sorters?: CrudSorting): string[] | undefined;
+//# sourceMappingURL=filters.d.ts.map

package/dist/filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.d.ts","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGhE;;;;;;;;;;yCAUyC;AACzC,wBAAgB,cAAc,CAAC,OAAO,GAAE,WAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAchF;AAED;uDACuD;AACvD,wBAAgB,WAAW,CAAC,OAAO,GAAE,WAAgB,GAAG,MAAM,EAAE,GAAG,SAAS,CAG3E"}

package/dist/filters.js

@@ -0,0 +1,33 @@
+import { filterValue, requireOperatorSuffix } from "./filter-operators.js";
+/** Converts refine's `CrudFilters` into the generated REST list route's
+ *  flat `field__operator=value` query-param convention (`RpcResourceMap`'s
+ *  sibling `toRpcQueryFilters` in `rpc-filters.ts` does the same mapping
+ *  for the RPC transport's `RpcListPredicate[]` shape — see
+ *  `filter-operators.ts` for the shared operator table both draw from).
+ *  refine operators with no cratestack equivalent — `endswith`,
+ *  `between`, `nin`, `containss`, and every refine conditional-filter
+ *  group (`or`/`and`) — **throw** rather than silently dropping the
+ *  filter: a dropped filter would show the caller an unfiltered result
+ *  set as if it were filtered, which is worse than an error because
+ *  nothing signals the data is wrong. */
+export function toQueryFilters(filters = []) {
+    const output = {};
+    for (const filter of filters) {
+        if (!("field" in filter)) {
+            throw new Error(`refine "${filter.operator}" filter groups have no cratestack equivalent — ` +
+                "this dataProvider only supports a flat AND of per-field predicates");
+        }
+        const suffix = requireOperatorSuffix(filter.field, filter.operator);
+        const key = suffix ? `${filter.field}__${suffix}` : filter.field;
+        output[key] = filterValue(filter.operator, filter.value);
+    }
+    return output;
+}
+/** refine `CrudSorting` -> the generated list route's `sort` query
+ *  values (`field` ascending, `-field` descending). */
+export function toSortQuery(sorters = []) {
+    if (sorters.length === 0)
+        return undefined;
+    return sorters.map((s) => (s.order === "desc" ? `-${s.field}` : s.field));
+}
+//# sourceMappingURL=filters.js.map

package/dist/filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.js","sourceRoot":"","sources":["../src/filters.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE3E;;;;;;;;;;yCAUyC;AACzC,MAAM,UAAU,cAAc,CAAC,OAAO,GAAgB,EAAE;IACtD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,WAAW,MAAM,CAAC,QAAQ,kDAAkD;gBAC1E,oEAAoE,CACvE,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;uDACuD;AACvD,MAAM,UAAU,WAAW,CAAC,OAAO,GAAgB,EAAE;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { DataProvider } from "@refinedev/core";
+import type { ResourceMap } from "./types.js";
+export { isCratestackHttpError, toRefineError } from "./errors.js";
+export { toQueryFilters, toSortQuery } from "./filters.js";
+export { toRpcQueryFilters, toRpcSortQuery } from "./rpc-filters.js";
+export type { CreateCratestackRpcDataProviderOptions } from "./rpc-provider.js";
+export { createCratestackRpcDataProvider } from "./rpc-provider.js";
+export type { CratestackRpcCallOptions, CratestackRpcListQuery, CratestackRpcModelApi, RpcListPredicate, RpcResourceConfig, RpcResourceMap, } from "./rpc-types.js";
+export type { CratestackFetchQuery, CratestackHttpErrorLike, CratestackModelApi, CratestackPage, CratestackRequestConfig, ResourceConfig, ResourceMap, } from "./types.js";
+export interface CreateCratestackDataProviderOptions {
+    /** Backs `getApiUrl()`. Defaults to `() => ""` — refine rarely calls
+     *  this in practice, but a real generated client's own origin/basePath
+     *  is available at `client.runtime.origin` / `client.runtime.basePath`
+     *  if a consumer needs an accurate value. */
+    getApiUrl?: () => string;
+    /** Backs `custom()`, refine's escape hatch for a cratestack `procedure`
+     *  call — there's nowhere else in a `DataProvider` for one to live.
+     *  Keyed by procedure name, called as `client.procedures.<name>`
+     *  would be; `custom({ meta: { procedure: "<name>" }, payload })`
+     *  dispatches to `procedures[name](payload)`. Omit if the schema has
+     *  no procedures a refine app needs to call. */
+    procedures?: Record<string, (args: unknown) => Promise<unknown>>;
+}
+/** Builds a refine `DataProvider` over one or more cratestack generated
+ *  REST model classes (`client.widgets`, `client.ledgers`, …), given a
+ *  manifest describing each resource's primary-key field, `@@paged`
+ *  status, and `@version` field.
+ *
+ *  Write that manifest by hand, or generate it: `cratestack
+ *  generate-typescript --refine` emits a `src/refine.ts` next to the
+ *  client whose `cratestackRefineResources(client)` returns exactly this
+ *  {@link ResourceMap}. The provider itself is not generated and has no
+ *  CLI subcommand — see the package README's "A runtime package with a
+ *  generated manifest" section for the split.
+ *
+ *  RPC-transport schemas aren't wired here — see the README's "REST
+ *  only" note. */
+export declare function createCratestackDataProvider(resources: ResourceMap, options?: CreateCratestackDataProviderOptions): DataProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EASV,YAAY,EAeb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAwD,WAAW,EAAE,MAAM,YAAY,CAAC;AAGpG,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,sCAAsC,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AACpE,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AAwBpB,MAAM,WAAW,mCAAmC;IAClD;;;iDAG6C;IAC7C,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB;;;;;oDAKgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;CAClE;AAED;;;;;;;;;;;;;kBAakB;AAClB,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,WAAW,EACtB,OAAO,GAAE,mCAAwC,GAChD,YAAY,CAoNd"}