@firsthandjs/data 0.5.0

package/dist/index.dev.js

@@ -0,0 +1,562 @@
+// packages/data/src/resource.ts
+import {
+  createContext,
+  effect,
+  onCleanup,
+  untrack,
+  useContext
+} from "@firsthandjs/core";
+
+// packages/data/src/store.ts
+import { batch, signal } from "@firsthandjs/core";
+
+// packages/data/src/tags.ts
+var NO_VARS = Object.freeze({});
+function tag(name, vars = NO_VARS) {
+  return { name, vars };
+}
+function tagMatches(pattern, candidate) {
+  if (pattern.name !== candidate.name) {
+    return false;
+  }
+  for (const name of Object.keys(pattern.vars)) {
+    if (!Object.is(pattern.vars[name], candidate.vars[name])) {
+      return false;
+    }
+  }
+  return true;
+}
+function anyTagMatches(patterns, tags) {
+  for (const pattern of patterns) {
+    for (const candidate of tags) {
+      if (tagMatches(pattern, candidate)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// packages/data/src/dev.ts
+function hook() {
+  const installed = globalThis.__FIRSTHAND_DEVTOOLS__;
+  return installed !== void 0 && installed.attached ? installed : void 0;
+}
+function devQuery(event, key, tags) {
+  hook()?.query(event, key, tags.map(readable));
+}
+function readable(value) {
+  const names = Object.keys(value.vars).sort();
+  if (names.length === 0) {
+    return value.name;
+  }
+  const vars = names.map((name) => `${name}: ${String(value.vars[name])}`).join(", ");
+  return `${value.name}(${vars})`;
+}
+
+// packages/data/src/store.ts
+function createData(options = {}) {
+  const held = /* @__PURE__ */ new Set();
+  return {
+    storage: options.storage,
+    hold: (entry) => {
+      held.add(entry);
+      return () => held.delete(entry);
+    },
+    invalidate: async (...patterns) => {
+      const waiting = [];
+      for (const entry of [...held]) {
+        if (entry.controller !== null) {
+          entry.pending.push(...patterns);
+        }
+        if (!anyTagMatches(patterns, entry.tags)) {
+          continue;
+        }
+        devQuery("invalidated", entry.name ?? "(call site)", entry.tags);
+        waiting.push(entry.run(true));
+      }
+      await Promise.all(waiting);
+    },
+    clear: () => {
+      for (const entry of [...held]) {
+        entry.controller?.abort();
+        held.delete(entry);
+      }
+      try {
+        options.storage?.clear?.();
+      } catch {
+      }
+    },
+    get size() {
+      return held.size;
+    }
+  };
+}
+function createHeld(store, name) {
+  const entry = {
+    data: signal(void 0),
+    error: signal(void 0),
+    status: signal("idle"),
+    loading: signal(false),
+    tags: [],
+    controller: null,
+    pending: [],
+    superseded: false,
+    disposed: false,
+    name
+  };
+  return entry;
+}
+function succeed(entry, value) {
+  batch(() => {
+    entry.data.value = value;
+    entry.error.value = void 0;
+    entry.status.value = "success";
+    entry.loading.value = false;
+  });
+}
+function fail(entry, error) {
+  batch(() => {
+    entry.error.value = error;
+    entry.status.value = "error";
+    entry.loading.value = false;
+  });
+}
+function expose(entry, release) {
+  return {
+    data: entry.data,
+    error: entry.error,
+    status: entry.status,
+    loading: entry.loading,
+    reload: () => entry.run(true),
+    dispose: () => {
+      entry.disposed = true;
+      entry.controller?.abort();
+      release();
+    }
+  };
+}
+
+// packages/data/src/resource.ts
+var DataContext = createContext();
+function useData() {
+  return useContext(DataContext).value;
+}
+function useInvalidate() {
+  const store = useData();
+  return (...patterns) => store.invalidate(...patterns);
+}
+function useResource(load, options = {}) {
+  const store = useData();
+  const entry = createHeld(store, options.persist);
+  const release = store.hold(entry);
+  devQuery("created", options.persist ?? "(call site)", []);
+  entry.run = (force) => {
+    if (entry.disposed) {
+      return Promise.resolve(void 0);
+    }
+    entry.controller?.abort();
+    const controller = new AbortController();
+    entry.controller = controller;
+    entry.pending = [];
+    entry.superseded = false;
+    entry.loading.value = true;
+    if (entry.data.peek() === void 0) {
+      entry.status.value = "loading";
+    }
+    const context = {
+      signal: controller.signal,
+      force,
+      tags: (...next) => {
+        entry.tags = next;
+        if (entry.pending.length > 0 && anyTagMatches(entry.pending, next)) {
+          entry.superseded = true;
+        }
+      }
+    };
+    return load(context).then(async (value) => {
+      if (controller.signal.aborted || entry.disposed) {
+        return void 0;
+      }
+      entry.controller = null;
+      succeed(entry, value);
+      if (options.persist !== void 0) {
+        try {
+          store.storage?.write?.(options.persist, value);
+        } catch {
+        }
+      }
+      if (entry.superseded) {
+        entry.superseded = false;
+        return entry.run(true);
+      }
+      return value;
+    }).catch((error) => {
+      if (controller.signal.aborted || entry.disposed) {
+        return void 0;
+      }
+      entry.controller = null;
+      fail(entry, error);
+      return void 0;
+    });
+  };
+  const persist = options.persist;
+  const storage = store.storage;
+  if (persist !== void 0 && storage?.read !== void 0) {
+    void (async () => {
+      try {
+        const stored = await storage.read?.(persist);
+        if (stored !== void 0 && entry.data.peek() === void 0 && !entry.disposed) {
+          succeed(entry, stored);
+          entry.loading.value = true;
+        }
+      } catch {
+      }
+    })();
+  }
+  effect(() => {
+    void entry.run(false);
+  });
+  onCleanup(() => {
+    entry.disposed = true;
+    entry.controller?.abort();
+    devQuery("dropped", options.persist ?? "(call site)", entry.tags);
+    release();
+  });
+  return expose(entry, release);
+}
+function useAction(run) {
+  const store = useData();
+  const entry = createHeld(store, void 0);
+  let controller = null;
+  onCleanup(() => {
+    entry.disposed = true;
+    controller?.abort();
+  });
+  return {
+    data: entry.data,
+    error: entry.error,
+    status: entry.status,
+    running: entry.loading,
+    run: async (input) => {
+      controller?.abort();
+      controller = new AbortController();
+      const current = controller;
+      let invalidating = [];
+      entry.loading.value = true;
+      entry.status.value = "loading";
+      try {
+        const result = await untrack(
+          () => run(input, {
+            signal: current.signal,
+            invalidates: (...tags) => {
+              invalidating = tags;
+            }
+          })
+        );
+        if (current.signal.aborted || entry.disposed) {
+          return void 0;
+        }
+        succeed(entry, result);
+        if (invalidating.length > 0) {
+          await store.invalidate(...invalidating);
+        }
+        return result;
+      } catch (error) {
+        if (current.signal.aborted || entry.disposed) {
+          return void 0;
+        }
+        fail(entry, error);
+        return void 0;
+      }
+    }
+  };
+}
+function fromObservable(source, options = {}) {
+  const store = useData();
+  const entry = createHeld(store, void 0);
+  const release = store.hold(entry);
+  entry.run = () => options.reload === void 0 ? Promise.resolve(void 0) : void_(options.reload());
+  entry.loading.value = true;
+  entry.status.value = "loading";
+  const subscription = source.subscribe({
+    // A source that pushes after the scope has gone is pushing into nothing:
+    // the cells are still there, but nobody is reading them.
+    next: (value) => {
+      succeed(entry, value);
+    },
+    error: (error) => {
+      fail(entry, error);
+    }
+  });
+  const stop = typeof subscription === "function" ? subscription : () => {
+    subscription.unsubscribe();
+  };
+  onCleanup(() => {
+    entry.disposed = true;
+    stop();
+    release();
+  });
+  return expose(entry, () => {
+    stop();
+    release();
+  });
+}
+function fromPromise(factory) {
+  return useResource(() => factory());
+}
+async function void_(promise) {
+  await promise;
+  return void 0;
+}
+
+// packages/data/src/document.ts
+var DIRECTIVE = /^@(tag|invalidates)\b/;
+var OPERATION = /\b(query|mutation|subscription)\b[^\S\n]*([A-Za-z_]\w*)?/;
+var NAME = /^[_A-Za-z][_0-9A-Za-z]*/;
+var FirsthandDirectiveError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FirsthandDirectiveError";
+  }
+};
+function endOfString(source, start) {
+  if (source.startsWith('"""', start)) {
+    const close = source.indexOf('"""', start + 3);
+    return close === -1 ? source.length : close + 3;
+  }
+  let at = start + 1;
+  while (at < source.length && source[at] !== '"') {
+    at += source[at] === "\\" ? 2 : 1;
+  }
+  return at + 1;
+}
+function endOfArguments(source, start) {
+  let depth = 0;
+  let at = start;
+  while (at < source.length) {
+    const character = source[at];
+    if (character === '"') {
+      at = endOfString(source, at);
+      continue;
+    }
+    if (character === "(" || character === "[" || character === "{") {
+      depth++;
+    } else if (character === ")" || character === "]" || character === "}") {
+      depth--;
+      if (depth === 0) {
+        return at + 1;
+      }
+    }
+    at++;
+  }
+  throw new FirsthandDirectiveError(`unclosed arguments in ${source.slice(start, start + 40)}`);
+}
+function unquote(quoted, directive) {
+  try {
+    return JSON.parse(quoted);
+  } catch {
+    throw new FirsthandDirectiveError(`@${directive}: ${quoted} is not a valid string`);
+  }
+}
+function parseArguments(raw, directive) {
+  const vars = {};
+  let at = 0;
+  const skipIgnored = () => {
+    while (at < raw.length && /[\s,]/.test(raw[at])) {
+      at++;
+    }
+  };
+  skipIgnored();
+  while (at < raw.length) {
+    const name = NAME.exec(raw.slice(at));
+    if (name === null) {
+      throw new FirsthandDirectiveError(
+        `@${directive}: expected an argument name at "${raw.slice(at)}"`
+      );
+    }
+    at += name[0].length;
+    skipIgnored();
+    if (raw[at] !== ":") {
+      throw new FirsthandDirectiveError(`@${directive}: argument ${name[0]} has no value`);
+    }
+    at++;
+    skipIgnored();
+    const read = readValue(raw, directive, at);
+    vars[name[0]] = read.value;
+    at = read.next;
+    skipIgnored();
+  }
+  return vars;
+}
+function readValue(raw, directive, at) {
+  const character = raw[at];
+  if (character === "$") {
+    const name = NAME.exec(raw.slice(at + 1));
+    if (name === null) {
+      throw new FirsthandDirectiveError(`@${directive}: expected a variable name after $`);
+    }
+    return { value: { variable: name[0] }, next: at + 1 + name[0].length };
+  }
+  if (character === '"') {
+    const end = endOfString(raw, at);
+    const quoted = raw.slice(at, end);
+    const literal = quoted.startsWith('"""') ? quoted.slice(3, -3).trim() : unquote(quoted, directive);
+    return { value: { literal }, next: end };
+  }
+  if (character === "[" || character === "{") {
+    throw new FirsthandDirectiveError(
+      `@${directive}: a tag variable must be a scalar, not a list or object`
+    );
+  }
+  const word = /^[^\s,)]+/.exec(raw.slice(at));
+  if (word === null) {
+    throw new FirsthandDirectiveError(`@${directive}: expected a value`);
+  }
+  const text = word[0];
+  const next = at + text.length;
+  if (text === "true" || text === "false") {
+    return { value: { literal: text === "true" }, next };
+  }
+  if (text === "null") {
+    return { value: { literal: null }, next };
+  }
+  const asNumber = Number(text);
+  return { value: { literal: Number.isNaN(asNumber) ? text : asNumber }, next };
+}
+function scan(source) {
+  const tags = [];
+  const invalidates = [];
+  let stripped = "";
+  let at = 0;
+  let kept = 0;
+  while (at < source.length) {
+    const character = source[at];
+    if (character === '"') {
+      at = endOfString(source, at);
+      continue;
+    }
+    if (character === "#") {
+      const newline = source.indexOf("\n", at);
+      at = newline === -1 ? source.length : newline;
+      continue;
+    }
+    if (character !== "@") {
+      at++;
+      continue;
+    }
+    const directive = DIRECTIVE.exec(source.slice(at));
+    if (directive === null) {
+      at++;
+      continue;
+    }
+    let end = at + directive[0].length;
+    let args = "";
+    let probe = end;
+    while (probe < source.length && /\s/.test(source[probe])) {
+      probe++;
+    }
+    if (source[probe] === "(") {
+      const close = endOfArguments(source, probe);
+      args = source.slice(probe + 1, close - 1);
+      end = close;
+    }
+    const vars = parseArguments(args, directive[1]);
+    const named = vars["name"];
+    if (named === void 0 || !("literal" in named) || typeof named.literal !== "string") {
+      throw new FirsthandDirectiveError(
+        `@${directive[1]} needs a literal name, as in @${directive[1]}(name: "user", id: $id)`
+      );
+    }
+    delete vars["name"];
+    (directive[1] === "tag" ? tags : invalidates).push({ name: named.literal, vars });
+    let from = at;
+    while (from > kept && /\s/.test(source[from - 1])) {
+      from--;
+    }
+    stripped += source.slice(kept, from);
+    kept = end;
+    at = end;
+  }
+  return { tags, invalidates, stripped: stripped + source.slice(kept) };
+}
+function parseGraphQL(source) {
+  const { tags, invalidates, stripped } = scan(source);
+  const operation = OPERATION.exec(stripped.replace(/#[^\n]*/g, ""));
+  return {
+    source: stripped,
+    operation: operation?.[2] ?? "",
+    kind: operation?.[1] ?? "query",
+    tags,
+    invalidates
+  };
+}
+function resolveTags(templates, variables) {
+  return templates.map((template) => {
+    const vars = {};
+    for (const [name, value] of Object.entries(template.vars)) {
+      if ("literal" in value) {
+        vars[name] = value.literal;
+        continue;
+      }
+      const bound = variables[value.variable];
+      if (bound !== void 0 && bound !== null) {
+        vars[name] = typeof bound === "object" ? JSON.stringify(bound) : bound;
+      }
+    }
+    return tag(template.name, vars);
+  });
+}
+
+// packages/data/src/http.ts
+var FirsthandHttpError = class extends Error {
+  constructor(status, url, body) {
+    super(`HTTP ${String(status)} for ${url}`);
+    this.status = status;
+    this.url = url;
+    this.body = body;
+    this.name = "FirsthandHttpError";
+  }
+  status;
+  url;
+  body;
+};
+function json(input, init = {}) {
+  return async ({ signal: signal2 }) => {
+    const { json: payload, ...rest } = init;
+    const options = { ...rest, signal: signal2 };
+    if (payload !== void 0) {
+      options.body = JSON.stringify(payload);
+      const headers = new Headers(init.headers);
+      if (!headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+      }
+      options.headers = headers;
+    }
+    const response = await fetch(input, options);
+    const text = await response.text();
+    const parsed = text === "" ? void 0 : JSON.parse(text);
+    if (!response.ok) {
+      throw new FirsthandHttpError(response.status, input, parsed);
+    }
+    return parsed;
+  };
+}
+export {
+  DataContext,
+  FirsthandDirectiveError,
+  FirsthandHttpError,
+  anyTagMatches,
+  createData,
+  fromObservable,
+  fromPromise,
+  json,
+  parseGraphQL,
+  resolveTags,
+  tag,
+  tagMatches,
+  useAction,
+  useData,
+  useInvalidate,
+  useResource
+};

package/dist/index.js

@@ -0,0 +1,2 @@
+import{createContext as I,effect as H,onCleanup as S,untrack as N,useContext as q}from"@firsthandjs/core";import{batch as O,signal as x}from"@firsthandjs/core";var j=Object.freeze({});function R(e,t=j){return{name:e,vars:t}}function D(e,t){if(e.name!==t.name)return!1;for(let r of Object.keys(e.vars))if(!Object.is(e.vars[r],t.vars[r]))return!1;return!0}function p(e,t){for(let r of e)for(let n of t)if(D(r,n))return!0;return!1}function C(e={}){let t=new Set;return{storage:e.storage,hold:r=>(t.add(r),()=>t.delete(r)),invalidate:async(...r)=>{let n=[];for(let a of[...t])a.controller!==null&&a.pending.push(...r),p(r,a.tags)&&(a.name,a.tags,n.push(a.run(!0)));await Promise.all(n)},clear:()=>{for(let r of[...t])r.controller?.abort(),t.delete(r);try{e.storage?.clear?.()}catch{}},get size(){return t.size}}}function b(e,t){return{data:x(void 0),error:x(void 0),status:x("idle"),loading:x(!1),tags:[],controller:null,pending:[],superseded:!1,disposed:!1,name:t}}function f(e,t){O(()=>{e.data.value=t,e.error.value=void 0,e.status.value="success",e.loading.value=!1})}function v(e,t){O(()=>{e.error.value=t,e.status.value="error",e.loading.value=!1})}function k(e,t){return{data:e.data,error:e.error,status:e.status,loading:e.loading,reload:()=>e.run(!0),dispose:()=>{e.disposed=!0,e.controller?.abort(),t()}}}var P=I();function m(){return q(P).value}function Q(){let e=m();return(...t)=>e.invalidate(...t)}function A(e,t={}){let r=m(),n=b(r,t.persist),a=r.hold(n);t.persist,n.run=i=>{if(n.disposed)return Promise.resolve(void 0);n.controller?.abort();let l=new AbortController;n.controller=l,n.pending=[],n.superseded=!1,n.loading.value=!0,n.data.peek()===void 0&&(n.status.value="loading");let u={signal:l.signal,force:i,tags:(...d)=>{n.tags=d,n.pending.length>0&&p(n.pending,d)&&(n.superseded=!0)}};return e(u).then(async d=>{if(!(l.signal.aborted||n.disposed)){if(n.controller=null,f(n,d),t.persist!==void 0)try{r.storage?.write?.(t.persist,d)}catch{}return n.superseded?(n.superseded=!1,n.run(!0)):d}}).catch(d=>{l.signal.aborted||n.disposed||(n.controller=null,v(n,d))})};let o=t.persist,s=r.storage;return o!==void 0&&s?.read!==void 0&&(async()=>{try{let i=await s.read?.(o);i!==void 0&&n.data.peek()===void 0&&!n.disposed&&(f(n,i),n.loading.value=!0)}catch{}})(),H(()=>{n.run(!1)}),S(()=>{n.disposed=!0,n.controller?.abort(),t.persist,n.tags,a()}),k(n,a)}function E(e){let t=m(),r=b(t,void 0),n=null;return S(()=>{r.disposed=!0,n?.abort()}),{data:r.data,error:r.error,status:r.status,running:r.loading,run:async a=>{n?.abort(),n=new AbortController;let o=n,s=[];r.loading.value=!0,r.status.value="loading";try{let i=await N(()=>e(a,{signal:o.signal,invalidates:(...l)=>{s=l}}));return o.signal.aborted||r.disposed?void 0:(f(r,i),s.length>0&&await t.invalidate(...s),i)}catch(i){if(o.signal.aborted||r.disposed)return;v(r,i);return}}}}function _(e,t={}){let r=m(),n=b(r,void 0),a=r.hold(n);n.run=()=>t.reload===void 0?Promise.resolve(void 0):J(t.reload()),n.loading.value=!0,n.status.value="loading";let o=e.subscribe({next:i=>{f(n,i)},error:i=>{v(n,i)}}),s=typeof o=="function"?o:()=>{o.unsubscribe()};return S(()=>{n.disposed=!0,s(),a()}),k(n,()=>{s(),a()})}function z(e){return A(()=>e())}async function J(e){await e}var M=/^@(tag|invalidates)\b/,G=/\b(query|mutation|subscription)\b[^\S\n]*([A-Za-z_]\w*)?/,L=/^[_A-Za-z][_0-9A-Za-z]*/,c=class extends Error{constructor(t){super(t),this.name="FirsthandDirectiveError"}};function V(e,t){if(e.startsWith('"""',t)){let n=e.indexOf('"""',t+3);return n===-1?e.length:n+3}let r=t+1;for(;r<e.length&&e[r]!=='"';)r+=e[r]==="\\"?2:1;return r+1}function B(e,t){let r=0,n=t;for(;n<e.length;){let a=e[n];if(a==='"'){n=V(e,n);continue}if(a==="("||a==="["||a==="{")r++;else if((a===")"||a==="]"||a==="}")&&(r--,r===0))return n+1;n++}throw new c(`unclosed arguments in ${e.slice(t,t+40)}`)}function F(e,t){try{return JSON.parse(e)}catch{throw new c(`@${t}: ${e} is not a valid string`)}}function Z(e,t){let r={},n=0,a=()=>{for(;n<e.length&&/[\s,]/.test(e[n]);)n++};for(a();n<e.length;){let o=L.exec(e.slice(n));if(o===null)throw new c(`@${t}: expected an argument name at "${e.slice(n)}"`);if(n+=o[0].length,a(),e[n]!==":")throw new c(`@${t}: argument ${o[0]} has no value`);n++,a();let s=W(e,t,n);r[o[0]]=s.value,n=s.next,a()}return r}function W(e,t,r){let n=e[r];if(n==="$"){let l=L.exec(e.slice(r+1));if(l===null)throw new c(`@${t}: expected a variable name after $`);return{value:{variable:l[0]},next:r+1+l[0].length}}if(n==='"'){let l=V(e,r),u=e.slice(r,l);return{value:{literal:u.startsWith('"""')?u.slice(3,-3).trim():F(u,t)},next:l}}if(n==="["||n==="{")throw new c(`@${t}: a tag variable must be a scalar, not a list or object`);let a=/^[^\s,)]+/.exec(e.slice(r));if(a===null)throw new c(`@${t}: expected a value`);let o=a[0],s=r+o.length;if(o==="true"||o==="false")return{value:{literal:o==="true"},next:s};if(o==="null")return{value:{literal:null},next:s};let i=Number(o);return{value:{literal:Number.isNaN(i)?o:i},next:s}}function K(e){let t=[],r=[],n="",a=0,o=0;for(;a<e.length;){let s=e[a];if(s==='"'){a=V(e,a);continue}if(s==="#"){let g=e.indexOf(`
+`,a);a=g===-1?e.length:g;continue}if(s!=="@"){a++;continue}let i=M.exec(e.slice(a));if(i===null){a++;continue}let l=a+i[0].length,u="",d=l;for(;d<e.length&&/\s/.test(e[d]);)d++;if(e[d]==="("){let g=B(e,d);u=e.slice(d+1,g-1),l=g}let w=Z(u,i[1]),T=w.name;if(T===void 0||!("literal"in T)||typeof T.literal!="string")throw new c(`@${i[1]} needs a literal name, as in @${i[1]}(name: "user", id: $id)`);delete w.name,(i[1]==="tag"?t:r).push({name:T.literal,vars:w});let y=a;for(;y>o&&/\s/.test(e[y-1]);)y--;n+=e.slice(o,y),o=l,a=l}return{tags:t,invalidates:r,stripped:n+e.slice(o)}}function U(e){let{tags:t,invalidates:r,stripped:n}=K(e),a=G.exec(n.replace(/#[^\n]*/g,""));return{source:n,operation:a?.[2]??"",kind:a?.[1]??"query",tags:t,invalidates:r}}function X(e,t){return e.map(r=>{let n={};for(let[a,o]of Object.entries(r.vars)){if("literal"in o){n[a]=o.literal;continue}let s=t[o.variable];s!=null&&(n[a]=typeof s=="object"?JSON.stringify(s):s)}return R(r.name,n)})}var h=class extends Error{constructor(r,n,a){super(`HTTP ${String(r)} for ${n}`);this.status=r;this.url=n;this.body=a;this.name="FirsthandHttpError"}status;url;body};function Y(e,t={}){return async({signal:r})=>{let{json:n,...a}=t,o={...a,signal:r};if(n!==void 0){o.body=JSON.stringify(n);let u=new Headers(t.headers);u.has("content-type")||u.set("content-type","application/json"),o.headers=u}let s=await fetch(e,o),i=await s.text(),l=i===""?void 0:JSON.parse(i);if(!s.ok)throw new h(s.status,e,l);return l}}export{P as DataContext,c as FirsthandDirectiveError,h as FirsthandHttpError,p as anyTagMatches,C as createData,_ as fromObservable,z as fromPromise,Y as json,U as parseGraphQL,X as resolveTags,R as tag,D as tagMatches,E as useAction,m as useData,Q as useInvalidate,A as useResource};

package/dist/resource.d.ts

@@ -0,0 +1,82 @@
+export { createData } from './store.js';
+import { type ActionContext, type DataStore, type LoadContext, type Resource, type Status } from './store.js';
+import { type Tag } from './tags.js';
+export declare const DataContext: import("@firsthandjs/core").Context<DataStore>;
+export declare function useData(): DataStore;
+/** Invalidates through the store this component is under. */
+export declare function useInvalidate(): (...patterns: Tag[]) => Promise<void>;
+export interface ResourceOptions {
+    /**
+     * A name to keep this resource's last value under, between visits.
+     *
+     * Persistence is the one thing that needs a name, because a name is what
+     * survives a reload — a call site does not. It is opt-in for that reason,
+     * and two resources sharing a name share what is stored, which is what
+     * naming them the same asks for.
+     */
+    readonly persist?: string;
+}
+/**
+ * Loads something, and keeps it as reactive state.
+ *
+ * ```tsx
+ * const user = useResource(async ({ signal, tags }) => {
+ *   tags(tag('user', { id: props.id }));
+ *   return (await fetch(`/api/users/${props.id}`, { signal })).json() as Promise<User>;
+ * });
+ * ```
+ *
+ * Everything read before the first `await` is a dependency, exactly as in an
+ * `effect` — including a token read to build a header. Read it with `peek()`
+ * if that is not what you want.
+ */
+export declare function useResource<T>(load: (context: LoadContext) => Promise<T>, options?: ResourceOptions): Resource<T>;
+export interface Action<I, R> {
+    readonly data: Resource<R>['data'];
+    readonly error: Resource<R>['error'];
+    readonly status: Resource<R>['status'];
+    readonly running: Resource<R>['loading'];
+    /** Runs it. Never rejects: failure is reported through `error`. */
+    run(input: I): Promise<R | undefined>;
+}
+/**
+ * Changes something, and says what it changed.
+ *
+ * ```tsx
+ * const rename = useAction(async (input: Rename, { signal, invalidates }) => {
+ *   const changed = await patch(input, signal);
+ *   invalidates(...changed.tags); // the server knows which user that was
+ *   return changed.user;
+ * });
+ * ```
+ */
+export declare function useAction<I, R>(run: (input: I, context: ActionContext) => Promise<R>): Action<I, R>;
+export interface ObservableLike<T> {
+    subscribe(observer: {
+        next?: (value: T) => void;
+        error?: (error: unknown) => void;
+    }): {
+        unsubscribe: () => void;
+    } | (() => void);
+}
+export interface BridgeOptions {
+    /** What `reload()` should do, if the source can do it. */
+    readonly reload?: () => Promise<unknown>;
+}
+/**
+ * A source that pushes, as a resource.
+ *
+ * For the case a per-call-site resource is the wrong shape: the same entity in
+ * twenty places, which must stay consistent. A normalising client already
+ * solves that, and this makes its observable a cell — one write in its cache,
+ * twenty views updated together.
+ *
+ * The contract is the smallest one every client satisfies: `subscribe` with a
+ * `next` and an `error`, returning either an unsubscribe function or something
+ * carrying one. Apollo, urql, RxJS and TanStack's `QueryObserver` all do.
+ */
+export declare function fromObservable<T>(source: ObservableLike<T>, options?: BridgeOptions): Resource<T>;
+/** A promise, as a resource. The loader form without tags or dependencies. */
+export declare function fromPromise<T>(factory: () => Promise<T>): Resource<T>;
+export type { LoadContext, ActionContext, Resource, Status };
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAiB,KAAK,GAAG,EAAE,MAAM,WAAW,CAAC;AAGpD,eAAO,MAAM,WAAW,gDAA6B,CAAC;AAEtD,wBAAgB,OAAO,IAAI,SAAS,CAEnC;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,IAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAGrE;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,OAAO,GAAE,eAAoB,GAC5B,QAAQ,CAAC,CAAC,CAAC,CAqGb;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,EAAE,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACzC,mEAAmE;IACnE,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GACpD,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAmDd;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,SAAS,CAAC,QAAQ,EAAE;QAClB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;KAClC,GAAG;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,OAAO,GAAE,aAAkB,GAC1B,QAAQ,CAAC,CAAC,CAAC,CAoCb;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAErE;AAQD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC"}