@firsthandjs/data 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+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,99 @@
+# @firsthandjs/data
+
+Resources, actions and invalidation for Firsthand: what is loaded, as reactive
+state, and when it has to be loaded again.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/09-data.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/data.md) · [ADR-0022](https://github.com/firsthandjs/firsthand/blob/main/docs/adr/0022-resources-not-a-cache.md)
+
+```
+npm install @firsthandjs/data
+```
+
+2.81 kB gzip. It depends on `@firsthandjs/core` and `@firsthandjs/dom`.
+
+```tsx
+const user = useResource(async ({ signal, tags }) => {
+  tags(tag('user', { id: props.id }));
+  return json<User>(`/api/users/${props.id}`)({ signal });
+});
+
+return <h1>{user.data.value?.name ?? '…'}</h1>;
+```
+
+No key, no name, no variables object. `props.id` is read inside the loader, so
+changing it runs the loader again and aborts what was in flight — exactly as an
+`effect` behaves, and for the same reason.
+
+## What it is not
+
+**It is not a cache.** A cache is defined by a second lookup for the same thing
+finding the first one's result, and that needs identity: a key, a name,
+something two callers agree on. Every form of that is a thing to forget or
+collide on. A resource belongs to its call site instead, and two call sites are
+two resources whatever their tags say.
+
+Deduplication, response caching and normalisation belong one layer down, where
+the knowledge of what is _the same thing_ actually lives — Apollo's cache, urql's
+`cacheExchange`, the browser's HTTP cache, or three lines of your own.
+
+| Layer         | Owns                                     | Who                           |
+| ------------- | ---------------------------------------- | ----------------------------- |
+| Normalisation | one entity, one truth, everywhere        | Apollo, urql-graphcache       |
+| Request cache | not asking twice                         | those clients, the HTTP cache |
+| **Resources** | **reactive state, status, invalidation** | **this package**              |
+
+## Tags are for invalidation
+
+They may be coarse, they may overlap, and two unrelated sources may share one.
+That is the feature — and it is safe, because they are not identity.
+
+```tsx
+const rename = useAction(async (input: Rename, { signal, invalidates }) => {
+  const changed = await json<Changed>(`/api/users/by-name/${input.name}`, {
+    method: 'PATCH',
+    json: input,
+    signal,
+  })({ signal });
+  // The client knew a name; only the server knows which id that was.
+  invalidates(...changed.tags);
+  return changed.user;
+});
+```
+
+Declare them where you know them: before the `await` when the caller does,
+after it when only the server does. `tags()` **replaces**, so a run says what
+it is about rather than accumulating what it used to be about.
+
+## Reaching past a cache
+
+The loader is told _why_ it is running. Without that, a transport cache would
+hand back the answer that was just invalidated:
+
+```tsx
+useResource(async ({ signal, force }) =>
+  json<User>('/api/users/5', { cache: force ? 'reload' : 'default' })({ signal }),
+);
+```
+
+`fetchPolicy: 'network-only'` for Apollo, `requestPolicy` for urql — the
+helper packages do it for you.
+
+## Bringing a client
+
+`@firsthandjs/data-axios`, `-urql` and `-apollo` bind an instance **you** built:
+your interceptors, your links, your authentication. None of them depends on the
+client it binds, so none of them has a version to follow.
+
+For GraphQL, tags come out of the `.gql` file as `@tag` / `@invalidates`
+directives, read at build time by `@firsthandjs/data/vite` and typed by
+`@firsthandjs/data/codegen`. The document that reaches your client is a plain
+object with the directives already removed.
+
+## What it deliberately does not do
+
+Interceptors, retries, backoff, token refresh, request de-duplication, progress
+events, XSRF, a Node adapter, normalisation, optimistic cache surgery,
+pagination helpers. Each belongs to a transport or to an application's own
+policy — and a loader takes any client, because it takes any function.
+
+MIT licensed.

package/dist/codegen.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A GraphQL Code Generator plugin that types your `.gql` imports.
+ *
+ * `@graphql-codegen/typescript-operations` writes `NotesQuery` and
+ * `NotesQueryVariables` from your schema. This writes the line that connects
+ * them to the file:
+ *
+ * ```ts
+ * declare module '*\/notes.gql' {
+ *   const document: GraphQLDocument<NotesQuery, NotesQueryVariables>;
+ *   export default document;
+ * }
+ * ```
+ *
+ * With that, nothing at a call site carries a type argument, and nothing can
+ * drift: the variables are checked against the operation, and the result is
+ * the shape the server actually returns.
+ *
+ * ```ts
+ * // codegen.ts
+ * import type { CodegenConfig } from '@graphql-codegen/cli';
+ *
+ * const config: CodegenConfig = {
+ *   schema: 'schema.graphql',
+ *   documents: 'src/**\/*.gql',
+ *   generates: {
+ *     'src/graphql-types.ts': { plugins: ['typescript', 'typescript-operations'] },
+ *     'src/graphql-modules.d.ts': {
+ *       plugins: ['@firsthandjs/data/codegen'],
+ *       config: { typesPath: './graphql-types' },
+ *     },
+ *   },
+ * };
+ * export default config;
+ * ```
+ *
+ * The declarations use wildcard module names (`*\/notes.gql`), which is how
+ * every codegen plugin of this kind works: TypeScript picks the most specific
+ * pattern, and the file stays a script rather than a module so the wildcards
+ * are legal.
+ */
+/** The bits of codegen's document shape this needs. Typed here to avoid a dependency. */
+export interface CodegenDocument {
+    readonly location?: string | undefined;
+    readonly document?: {
+        readonly definitions: readonly {
+            readonly kind: string;
+            readonly operation?: string;
+            readonly name?: {
+                readonly value: string;
+            } | undefined;
+        }[];
+    } | undefined;
+}
+export interface CodegenConfig {
+    /**
+     * Where `typescript-operations` wrote its types, relative to this file.
+     *
+     * Defaults to `./graphql-types`, which is what the example above generates.
+     */
+    readonly typesPath?: string;
+    /** Import path for the document type. Only useful when testing this plugin. */
+    readonly documentTypePath?: string;
+}
+/**
+ * Generates the module declarations.
+ *
+ * The signature is GraphQL Code Generator's: `(schema, documents, config)`.
+ * The schema is unused — the operation types come from the plugins that ran
+ * before this one.
+ */
+export declare function plugin(_schema: unknown, documents: readonly CodegenDocument[], config?: CodegenConfig): string;
+declare const _default: {
+    plugin: typeof plugin;
+};
+export default _default;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EACd;QACE,QAAQ,CAAC,WAAW,EAAE,SAAS;YAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE;gBAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;aAAE,GAAG,SAAS,CAAC;SACxD,EAAE,CAAC;KACL,GACD,SAAS,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AA8BD;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,SAAS,eAAe,EAAE,EACrC,MAAM,GAAE,aAAkB,GACzB,MAAM,CAgDR;;;;AAED,wBAA0B"}

package/dist/codegen.dev.js

@@ -0,0 +1,67 @@
+// packages/data/src/codegen.ts
+var SUFFIX = {
+  query: "Query",
+  mutation: "Mutation",
+  subscription: "Subscription"
+};
+function moduleName(location) {
+  const normalized = location.split("\\").join("/");
+  const file = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return `*/${file}`;
+}
+function operationOf(document) {
+  for (const definition of document?.definitions ?? []) {
+    if (definition.kind === "OperationDefinition" && definition.name !== void 0) {
+      return { name: definition.name.value, kind: definition.operation ?? "query" };
+    }
+  }
+  return null;
+}
+function plugin(_schema, documents, config = {}) {
+  const typesPath = config.typesPath ?? "./graphql-types";
+  const documentType = config.documentTypePath ?? "@firsthandjs/data";
+  const blocks = [];
+  const declared = /* @__PURE__ */ new Set();
+  for (const entry of documents) {
+    const location = entry.location;
+    if (location === void 0 || location === "") {
+      continue;
+    }
+    const operation = operationOf(entry.document);
+    if (operation === null) {
+      continue;
+    }
+    const name = moduleName(location);
+    if (declared.has(name)) {
+      continue;
+    }
+    declared.add(name);
+    const base = `${operation.name}${SUFFIX[operation.kind] ?? "Query"}`;
+    blocks.push(
+      [
+        `declare module '${name}' {`,
+        `  const document: import('${documentType}').GraphQLDocument<`,
+        `    import('${typesPath}').${base},`,
+        `    import('${typesPath}').${base}Variables`,
+        `  >;`,
+        `  export default document;`,
+        `}`
+      ].join("\n")
+    );
+  }
+  return [
+    "// Generated by @firsthandjs/data/codegen. Do not edit.",
+    "//",
+    "// Wildcard module declarations, so that importing a .gql file gives a",
+    "// document that knows its own result and variable types. Nothing here is",
+    "// a module: wildcards are only legal in a script.",
+    "",
+    ...blocks,
+    ""
+  ].join("\n");
+}
+var codegen_default = { plugin };
+export {
+  codegen_default as default,
+  plugin
+};

package/dist/codegen.js

@@ -0,0 +1,67 @@
+// packages/data/src/codegen.ts
+var SUFFIX = {
+  query: "Query",
+  mutation: "Mutation",
+  subscription: "Subscription"
+};
+function moduleName(location) {
+  const normalized = location.split("\\").join("/");
+  const file = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return `*/${file}`;
+}
+function operationOf(document) {
+  for (const definition of document?.definitions ?? []) {
+    if (definition.kind === "OperationDefinition" && definition.name !== void 0) {
+      return { name: definition.name.value, kind: definition.operation ?? "query" };
+    }
+  }
+  return null;
+}
+function plugin(_schema, documents, config = {}) {
+  const typesPath = config.typesPath ?? "./graphql-types";
+  const documentType = config.documentTypePath ?? "@firsthandjs/data";
+  const blocks = [];
+  const declared = /* @__PURE__ */ new Set();
+  for (const entry of documents) {
+    const location = entry.location;
+    if (location === void 0 || location === "") {
+      continue;
+    }
+    const operation = operationOf(entry.document);
+    if (operation === null) {
+      continue;
+    }
+    const name = moduleName(location);
+    if (declared.has(name)) {
+      continue;
+    }
+    declared.add(name);
+    const base = `${operation.name}${SUFFIX[operation.kind] ?? "Query"}`;
+    blocks.push(
+      [
+        `declare module '${name}' {`,
+        `  const document: import('${documentType}').GraphQLDocument<`,
+        `    import('${typesPath}').${base},`,
+        `    import('${typesPath}').${base}Variables`,
+        `  >;`,
+        `  export default document;`,
+        `}`
+      ].join("\n")
+    );
+  }
+  return [
+    "// Generated by @firsthandjs/data/codegen. Do not edit.",
+    "//",
+    "// Wildcard module declarations, so that importing a .gql file gives a",
+    "// document that knows its own result and variable types. Nothing here is",
+    "// a module: wildcards are only legal in a script.",
+    "",
+    ...blocks,
+    ""
+  ].join("\n");
+}
+var codegen_default = { plugin };
+export {
+  codegen_default as default,
+  plugin
+};

package/dist/dev.d.ts

@@ -0,0 +1,10 @@
+import type { Tag } from './tags.js';
+/**
+ * Reports what the cache just did.
+ *
+ * The cache is the one part of the framework whose behaviour is not visible in
+ * the reactive graph: a tag match is a decision, not an edge, and an
+ * invalidation that hits nothing looks exactly like one that was never sent.
+ */
+export declare function devQuery(event: string, key: string, tags: readonly Tag[]): void;
+//# sourceMappingURL=dev.d.ts.map

package/dist/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../src/dev.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAOrC;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,EAAE,GAAG,IAAI,CAE/E"}

package/dist/dev.prod.d.ts

@@ -0,0 +1,3 @@
+/** Production stub for `dev.ts`. Aliased in by the build; see `dev.ts`. */
+export declare function devQuery(_event: string, _key: string, _tags: readonly unknown[]): void;
+//# sourceMappingURL=dev.prod.d.ts.map

package/dist/dev.prod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.prod.d.ts","sourceRoot":"","sources":["../src/dev.prod.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAEtF"}

package/dist/document.d.ts

@@ -0,0 +1,98 @@
+/**
+ * GraphQL, with the tags written where the query is.
+ *
+ * A `.graphql` file already says what it reads. Repeating that in TypeScript as
+ * a cache key is how caches drift out of sync with the queries they hold, so
+ * the tag assignment lives in the document, as directives:
+ *
+ * ```graphql
+ * query User($id: ID!) @tag(name: "user", id: $id) @tag(name: "permissions") {
+ *   user(id: $id) {
+ *     id
+ *     name
+ *   }
+ * }
+ * ```
+ *
+ * and a mutation says what it breaks:
+ *
+ * ```graphql
+ * mutation RenameUser($id: ID!, $name: String!)
+ * @invalidates(name: "user", id: $id)
+ * @invalidates(name: "users") {
+ *   renameUser(id: $id, name: $name) {
+ *     id
+ *   }
+ * }
+ * ```
+ *
+ * `name` is the tag's name; every other argument is a tag variable. `$id` is
+ * bound from the variables the call passes, so one directive covers every user.
+ * A variable the call leaves out is dropped from the tag, which widens it —
+ * `user(id: $id)` with no `id` means "every user", which is the right answer
+ * for "I changed something and I do not know which one".
+ *
+ * The directives are **removed** from the document before it is sent. They are
+ * instructions to the cache, not to the server, and a server that has not
+ * declared them in its schema would reject the whole query — the same reason
+ * Apollo strips `@connection`. Put them on the operation, or on a field if
+ * that reads better; they are recognised and stripped wherever they appear.
+ */
+import { type Tag, type TagVars, type Variables } from './tags.js';
+/** A tag variable: either bound from a call's variables, or fixed. */
+export type TagValue = {
+    readonly variable: string;
+} | {
+    readonly literal: TagVars[string];
+};
+export interface TagTemplate {
+    readonly name: string;
+    readonly vars: Readonly<Record<string, TagValue>>;
+}
+/**
+ * A parsed operation, carrying what it returns and what it needs.
+ *
+ * `TData` and `TVariables` exist only in the type system — nothing writes
+ * them, and `JSON.stringify` of a document does not mention them. They are
+ * what lets `useGraphQL(NotesDocument)` know its own result type without a
+ * type argument at the call site, once `@firsthandjs/data/codegen` has written
+ * the declaration for the `.gql` file.
+ */
+export interface GraphQLDocument<TData = unknown, TVariables extends Variables = Record<string, never>> {
+    /** What is sent to the server: the document with the tag directives removed. */
+    readonly source: string;
+    /** The operation name, or `''` for an anonymous operation. */
+    readonly operation: string;
+    readonly kind: 'query' | 'mutation' | 'subscription';
+    readonly tags: readonly TagTemplate[];
+    readonly invalidates: readonly TagTemplate[];
+    /** Phantom: the shape this operation returns. Never present at runtime. */
+    readonly data?: TData;
+    /** Phantom: the variables this operation takes. Never present at runtime. */
+    readonly variables?: TVariables;
+}
+/**
+ * How a document's variables are passed: required when the operation has some,
+ * omitted when it has none.
+ *
+ * A tuple rather than `variables?:` so that an operation with required
+ * variables cannot be called without them, while one without may be called
+ * with the document alone. The helper packages take this, which is what checks
+ * a call against the schema it was generated from.
+ */
+export type DocumentArguments<TVariables extends Variables> = Record<string, never> extends TVariables ? [variables?: TVariables] : [variables: TVariables];
+/** Thrown for a tag directive the cache cannot make sense of. */
+export declare class FirsthandDirectiveError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reads a document's tag directives and returns it without them.
+ *
+ * Malformed directives throw. With the `@firsthandjs/data/vite` loader that
+ * happens at build time, which is where a typo in a cache instruction should
+ * be found.
+ */
+export declare function parseGraphQL<TData = unknown, TVariables extends Variables = Record<string, never>>(source: string): GraphQLDocument<TData, TVariables>;
+/** Binds tag templates against a call's variables. */
+export declare function resolveTags(templates: readonly TagTemplate[], variables: Variables): Tag[];
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAO,KAAK,GAAG,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAGxE,sEAAsE;AACtE,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAE7F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CACnD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAC9B,KAAK,GAAG,OAAO,EACf,UAAU,SAAS,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAEpD,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAAC,UAAU,SAAS,SAAS,IACxD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,UAAU,GAAG,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AAMhG,iEAAiE;AACjE,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAqND;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAG,OAAO,EAAE,UAAU,SAAS,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAChG,MAAM,EAAE,MAAM,GACb,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAYpC;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,EAAE,SAAS,EAAE,SAAS,GAAG,GAAG,EAAE,CAiB1F"}

package/dist/http.d.ts

@@ -0,0 +1,64 @@
+/**
+ * REST, which needs almost nothing.
+ *
+ * `fetch` is already the API; what a cache needs from it is an abort signal
+ * wired up and a failed status turned into a thrown error, because a promise
+ * that resolves with a 500 makes every caller write the same four lines.
+ */
+import type { LoadContext } from './store.js';
+/**
+ * Thrown for any response outside 2xx.
+ *
+ * Prefixed like every other error here, so that `instanceof` cannot be confused
+ * by an `HttpError` from somewhere else in an application.
+ */
+export declare class FirsthandHttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    /** The parsed body, if there was one. */
+    readonly body: unknown;
+    constructor(status: number, url: string, 
+    /** The parsed body, if there was one. */
+    body: unknown);
+}
+/**
+ * What `json` takes: `RequestInit`, plus the one thing the platform lacks.
+ *
+ * `method`, `credentials`, `mode`, `headers` and the rest are passed straight
+ * through. So is `body`: a `FormData`, a `URLSearchParams` or a `Blob` is
+ * labelled by the platform itself, boundary and all, and nothing here could
+ * improve on that.
+ *
+ * JSON is the exception, and the only one — measured: a stringified object is
+ * a string, so `fetch` labels it `text/plain`. `json:` is the two lines every
+ * codebase writes to fix that.
+ */
+export interface JsonRequest extends Omit<RequestInit, 'body'> {
+    readonly body?: BodyInit | null;
+    /** Sent as JSON, with the content type the platform will not set for you. */
+    readonly json?: unknown;
+}
+/**
+ * `fetch` for a JSON endpoint: the abort signal wired up, a failed status
+ * thrown, and the body parsed.
+ *
+ * ```ts
+ * const user = useResource(async ({ signal, tags }) => {
+ *   tags(tag('user', { id: props.id }));
+ *   return json<User>(`/api/users/${props.id}`)({ signal });
+ * });
+ * ```
+ *
+ * A write is the same call with a method and a body:
+ *
+ * ```ts
+ * json<Note>('/api/notes', { method: 'POST', json: { title } });
+ * json<Upload>('/api/files', { method: 'POST', body: formData });
+ * ```
+ *
+ * This is the platform, not a client. There is no base URL, no instance, no
+ * interceptor and no retry here, and there will not be: those belong to a
+ * client, and a loader takes any client because it takes any function.
+ */
+export declare function json<T>(input: string, init?: JsonRequest): (context: Pick<LoadContext, 'signal'>) => Promise<T>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO;gBAHb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM;IACpB,yCAAyC;IAChC,IAAI,EAAE,OAAO;CAKzB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,WAAgB,GACrB,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAwBtD"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@firsthandjs/data` — resources, actions and invalidation.
+ *
+ * What is loaded, as reactive state; what it is about, as tags; and when it
+ * has to be loaded again. Not a cache: deduplication, response caching and
+ * normalisation belong to the transport, where the knowledge of what is the
+ * same thing lives (ADR-0022).
+ */
+export { createData, DataContext, useData, useInvalidate } from './resource.js';
+export { useResource, useAction, fromObservable, fromPromise } from './resource.js';
+export type { Action, ObservableLike, BridgeOptions, ResourceOptions } from './resource.js';
+export type { ActionContext, DataOptions, DataStore, LoadContext, Resource, Status, Storage, } from './store.js';
+export { tag, tagMatches, anyTagMatches } from './tags.js';
+export type { Tag, TagVars, Variables } from './tags.js';
+export { parseGraphQL, resolveTags, FirsthandDirectiveError } from './document.js';
+export type { DocumentArguments, GraphQLDocument, TagTemplate, TagValue } from './document.js';
+/**
+ * `fetch`, with the three things a resource needs from it.
+ *
+ * The platform, not a vendor: no base URLs, no instances, no interceptors, no
+ * retry. Those belong to a client, and a loader takes any client because it
+ * takes any function.
+ */
+export { json, FirsthandHttpError } from './http.js';
+export type { JsonRequest } from './http.js';
+//# 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;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACpF,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EACV,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,QAAQ,EACR,MAAM,EACN,OAAO,GACR,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACnF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE/F;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}