@weirdscience/based-client 0.2.0 → 0.3.0

package/README.md

@@ -60,6 +60,41 @@ const { data, total, isLoading } = useQuery("posts", {
 });
 ```
 
+Gate the query behind auth or any boolean with `enabled`:
+
+```tsx
+const { user } = useUser();
+const { data } = useQuery("notes", { enabled: !!user });
+// Won't fire until `user` is truthy — avoids a 403 when signed out.
+```
+
+### `useRecord(table, id, options?)`
+
+Fetch a single record by id via `GET /api/:table/:id`. Returns `{ data, isLoading, error, refetch }` — `data` is a single row, not an array.
+
+```tsx
+import { useRecord } from "@weirdscience/based-client";
+
+function Post({ id }: { id: string }) {
+  const { data: post, isLoading } = useRecord("posts", id);
+  if (isLoading) return <Spinner />;
+  if (!post) return <NotFound />;
+  return <h1>{post.title}</h1>;
+}
+```
+
+Pass `null`/`undefined` as the id to skip the query (same effect as `enabled: false`):
+
+```tsx
+const { data } = useRecord("posts", selectedId); // no fetch until selectedId is set
+```
+
+Perfect for deterministic keys like `${userId}:${key}`:
+
+```tsx
+const { data: prefs } = useRecord("preferences", `${user.id}:theme`);
+```
+
 ### `useMutation(table, operation)`
 
 Write rows. `operation` is `"create" | "update" | "delete"`. Returns `{ mutate, isLoading, error }`.

package/dist/hooks/use-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-query.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzE,wBAAgB,QAAQ,CACtB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,EACjE,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,EAE7C,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3B,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAiDnB"}
+{"version":3,"file":"use-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-query.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzE,wBAAgB,QAAQ,CACtB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,EACjE,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,EAE7C,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3B,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAyDnB"}

package/dist/hooks/use-record.d.ts

@@ -0,0 +1,3 @@
+import type { RecordOptions, RecordResult, DefaultTables } from "../types";
+export declare function useRecord<T extends Record<string, Record<string, unknown>> = DefaultTables, K extends string & keyof T = string & keyof T>(table: K, id: string | null | undefined, options?: RecordOptions): RecordResult<T[K]>;
+//# sourceMappingURL=use-record.d.ts.map

package/dist/hooks/use-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-record.d.ts","sourceRoot":"","sources":["../../src/hooks/use-record.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE3E,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,EACjE,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,EAE7C,KAAK,EAAE,CAAC,EACR,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CA8CpB"}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { createClient } from "./client";
 export { BasedProvider, useBasedClient } from "./provider";
 export { useUser } from "./hooks/use-user";
 export { useQuery } from "./hooks/use-query";
+export { useRecord } from "./hooks/use-record";
 export { useMutation } from "./hooks/use-mutation";
-export type { BasedClient, BasedClientOptions, AuthUser, AuthState, QueryOptions, QueryResult, MutationResult, DefaultTables, } from "./types";
+export type { BasedClient, BasedClientOptions, StorageAdapter, AuthUser, AuthState, QueryOptions, QueryResult, RecordOptions, RecordResult, MutationResult, DefaultTables, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,GACd,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -251,9 +251,10 @@ function useUser() {
 import { useState, useEffect, useCallback } from "react";
 function useQuery(table, options) {
   const client = useBasedClient();
+  const enabled = options?.enabled !== false;
   const [data, setData] = useState(null);
   const [total, setTotal] = useState(0);
-  const [isLoading, setIsLoading] = useState(true);
+  const [isLoading, setIsLoading] = useState(enabled);
   const [error, setError] = useState(null);
   const fetchData = useCallback(async () => {
     setIsLoading(true);
@@ -291,17 +292,69 @@ function useQuery(table, options) {
     }
   }, [client, table, JSON.stringify(options)]);
   useEffect(() => {
+    if (!enabled) {
+      setIsLoading(false);
+      setData(null);
+      setTotal(0);
+      setError(null);
+      return;
+    }
     fetchData();
-  }, [fetchData]);
+  }, [fetchData, enabled]);
   return { data, total, isLoading, error, refetch: fetchData };
 }
+// src/hooks/use-record.ts
+import { useState as useState2, useEffect as useEffect2, useCallback as useCallback2 } from "react";
+function useRecord(table, id, options) {
+  const client = useBasedClient();
+  const enabled = options?.enabled !== false && !!id;
+  const [data, setData] = useState2(null);
+  const [isLoading, setIsLoading] = useState2(enabled);
+  const [error, setError] = useState2(null);
+  const fetchData = useCallback2(async () => {
+    if (!id)
+      return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const res = await client.fetch(`/api/${table}/${encodeURIComponent(id)}`);
+      const json = await res.json();
+      if (!res.ok) {
+        if (res.status === 404) {
+          setData(null);
+          setError(null);
+        } else {
+          setError(json.error || { code: "UNKNOWN", message: "Request failed" });
+          setData(null);
+        }
+      } else {
+        setData(json.data);
+      }
+    } catch (err) {
+      setError({ code: "NETWORK_ERROR", message: err.message });
+      setData(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client, table, id]);
+  useEffect2(() => {
+    if (!enabled) {
+      setIsLoading(false);
+      setData(null);
+      setError(null);
+      return;
+    }
+    fetchData();
+  }, [fetchData, enabled]);
+  return { data, isLoading, error, refetch: fetchData };
+}
 // src/hooks/use-mutation.ts
-import { useState as useState2, useCallback as useCallback2 } from "react";
+import { useState as useState3, useCallback as useCallback3 } from "react";
 function useMutation(table, operation) {
   const client = useBasedClient();
-  const [isLoading, setIsLoading] = useState2(false);
-  const [error, setError] = useState2(null);
-  const mutate = useCallback2(async (data) => {
+  const [isLoading, setIsLoading] = useState3(false);
+  const [error, setError] = useState3(null);
+  const mutate = useCallback3(async (data) => {
     setIsLoading(true);
     setError(null);
     try {
@@ -350,6 +403,7 @@ function useMutation(table, operation) {
 }
 export {
   useUser,
+  useRecord,
   useQuery,
   useMutation,
   useBasedClient,

package/dist/types.d.ts

@@ -54,6 +54,11 @@ export interface QueryOptions<T = Record<string, unknown>> {
     filter?: Partial<Record<keyof T, string | number | boolean>>;
     limit?: number;
     offset?: number;
+    /**
+     * When false, the query won't fire. Useful for gating queries behind auth:
+     * `useQuery("notes", { enabled: !!user })`. Defaults to true.
+     */
+    enabled?: boolean;
 }
 export interface QueryResult<T = unknown> {
     data: T[] | null;
@@ -65,6 +70,21 @@ export interface QueryResult<T = unknown> {
     } | null;
     refetch: () => void;
 }
+export interface RecordOptions {
+    /**
+     * When false, the query won't fire.
+     */
+    enabled?: boolean;
+}
+export interface RecordResult<T = unknown> {
+    data: T | null;
+    isLoading: boolean;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    refetch: () => void;
+}
 export interface MutationResult<T = unknown> {
     mutate: (data: Partial<T> & Record<string, unknown>) => Promise<T>;
     isLoading: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weirdscience/based-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React SDK for Based — a minimal self-hosted BaaS",
   "license": "MIT",
   "repository": {