@burojs/hasura 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Kuznetsov
+
+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,122 @@
+# @burojs/hasura
+
+A [Hasura](https://hasura.io/) GraphQL data provider and live (subscription)
+provider for [buro](https://github.com/buro/buro).
+
+## Install
+
+```bash
+pnpm add @burojs/hasura @burojs/core
+```
+
+## Usage
+
+```ts
+import { createHasuraDataProvider } from '@burojs/hasura';
+
+const dataProvider = createHasuraDataProvider({
+  // Where to POST. Same-origin path, path-prefixed path, or absolute URL.
+  // Defaults to '/gql/v1/graphql'.
+  endpoint: '/gql/v1/graphql',
+  getToken: async () => session.jwt,
+  // X-Hasura-Role for resources that don't declare their own. Omit for none.
+  defaultRole: 'company-admin',
+  resources: {
+    orders: {
+      table: 'orders',
+      selectFields: ['id', 'code', 'status', 'created_at'],
+      pkType: 'uuid',
+      live: true,
+    },
+  },
+});
+```
+
+### `createHasuraDataProvider(config)`
+
+A `DataProvider` over Hasura's GraphQL API: `list` / `one` / `many` / `count`
+queries, `createOne` / `updateOne` / `deleteOne` mutations, an opt-in
+custom-operation registry, and a bundled live provider. Offset pagination only
+— cursor pagination is refused with a `capability` error.
+
+Everything the provider does is driven by the per-resource `ResourceMapping`
+registry rather than by branching on resource names:
+
+| Mapping field | What it declares |
+|---|---|
+| `table`, `selectFields` | the Hasura table and the columns to select |
+| `pkField`, `pkType` | primary-key column name and its GraphQL scalar (`bigint` \| `uuid` \| `Int` \| `String`) |
+| `byPkRoot` | the `<table>_by_pk` root name, or `false` when the role exposes only the collection root |
+| `aggregate`, `noAggregate` | whether a count root exists, and whether to pay for a count on every page |
+| `role` | per-resource `X-Hasura-Role` (`null` suppresses the header) |
+| `scopeFields` | which keys from `getScope()` this table actually has columns for |
+| `fixedFilter` | an always-on `where` fragment — several resource names over one table, each a different slice |
+| `int64Fields` | columns Hasura serialises as JSON strings (ClickHouse `int64`), whose filter values must be stringified |
+| `jsonbSpill` | route a flat form record into/out of JSONB `head` / `meta` columns |
+| `dataBody` | route a heavy array payload into/out of a 1:1 sibling table |
+| `live` | opt this resource into subscription-driven invalidation |
+
+#### `recoverAuth` fires on HTTP 401 — which is not how Hasura rejects a credential
+
+`config.recoverAuth` is consulted when a request comes back with HTTP **401**,
+and only then. The one capture in this repository of a real Hasura rejection —
+`packages/mock-kit/fixtures/hasura/error-unauthorized.json`, taken from a live
+backend with a deliberately malformed bearer token — came back **HTTP 200 with
+an `invalid-jwt` errors envelope**. Replayed through this provider that
+surfaces as `{ kind: 'protocol', code: 'graphql-error' }`, `recoverAuth` is
+never called, and app logic keyed on `kind: 'auth'` never fires either.
+
+So `recoverAuth` is useful for a deployment that really answers 401 (a proxy or
+gateway in front of Hasura); against Hasura's own rejection shape it is inert.
+The behaviour is pinned by `tests/fixture-fidelity.test.ts`'s
+`error-unauthorized` case, and the package's existing 401-recovery tests use a
+fabricated 401 — they are not evidence about Hasura. Keying recovery on the
+error envelope is a product decision this package has not taken.
+
+Optimistic concurrency is available per call: pass
+`providerOptions.ifUpdatedAt` on an update and the mutation switches to a
+`where`-guarded form, rejecting with `{ kind: 'conflict', code:
+'stale-record' }` when the row has moved on. Omit it (or pass `null`) and
+nothing changes.
+
+### `createHasuraLiveProvider(config)`
+
+The subscription half, already wired in by `createHasuraDataProvider`. Exported
+separately for callers that want it on its own. The socket carries only a
+change SIGNAL — rows always come back through the regular descriptor query, so
+mapping and pagination stay single-sourced in the data provider.
+`hasuraWsUrl(endpoint)` (also exported) is the http(s) → ws(s) conversion. Two
+things a caller has to know about it:
+
+- Its argument is the **full endpoint**, the same string you pass
+  `createHasuraDataProvider` — not a path prefix. It appends nothing. (The two
+  applications this package was distilled from had a same-named,
+  same-signature function that took a PREFIX and appended `/gql/v1/graphql`
+  itself; copying one of those call sites here yields a socket URL that
+  addresses nothing, and a socket that never connects does not throw. Pinned by
+  `tests/live-provider.test.ts`.)
+- The conversion needs a `window`. With none (SSR, or a non-browser import) the
+  endpoint is returned **unchanged** — an absolute `https://…` endpoint comes
+  back as `https://…`, not `wss://…`. A relative endpoint has no host to
+  resolve against there, so this is a real boundary, not just a scheme bug.
+
+## Provenance
+
+This package was distilled from two independently-evolved copies of the same
+provider that lived in two applications. The copies had drifted in exactly
+seven places; each resolution is documented in a comment next to the code it
+affects, saying which side it came from and whether it was a feature, a bug
+fix, or drift. Two defects that neither copy had fixed at the time were closed
+here, each with a test that reddens without the fix; both were subsequently
+backported into both applications, so the in-code notes describe the state this
+package was distilled FROM, not the state of the repository today.
+
+Neither application is migrated onto this package and neither has been removed
+yet, so at present the repository holds three copies of this provider rather
+than one. That is deliberate — the applications are leaving, so migrating them
+would be wasted work — but the de-duplication this package exists for is not
+complete until they go.
+
+## License
+
+MIT