@hypequery/react 0.0.0-canary-20260611154523

package/dist/createHooks.d.ts

@@ -0,0 +1,49 @@
+import { type UseQueryOptions as TanstackUseQueryOptions, type UseMutationOptions as TanstackUseMutationOptions, type UseMutationResult, type UseQueryResult } from '@tanstack/react-query';
+import type { ExtractNames, QueryInput, QueryOutput } from './types.js';
+import { HttpError } from './errors.js';
+export interface QueryMethodConfig {
+    method?: string;
+    path?: string;
+}
+/** A single route as produced by `@hypequery/serve`'s `api.manifest()`. */
+export interface RouteManifestEntry {
+    method?: string;
+    path?: string;
+}
+/**
+ * Map of query/metric/dataset keys to their HTTP method and full path. Pair
+ * with `InferAPIType` and `api.manifest()` from `@hypequery/serve` to resolve
+ * routes on the client without importing server code into the bundle.
+ */
+export type RouteManifest = Record<string, RouteManifestEntry>;
+type HeaderMap = Record<string, string | undefined>;
+type HeadersInput = HeaderMap | (() => HeaderMap);
+export interface CreateHooksConfig<TApi = Record<string, {
+    input: unknown;
+    output: unknown;
+}>> {
+    baseUrl: string;
+    fetchFn?: typeof fetch;
+    headers?: HeadersInput;
+    config?: Record<string, QueryMethodConfig>;
+    /**
+     * Route manifest from `@hypequery/serve`'s `api.manifest()`. Resolves the
+     * method and full path for each key — required for metric/dataset endpoints,
+     * which are POST routes whose paths differ from their map keys.
+     */
+    manifest?: RouteManifest;
+    api?: TApi;
+}
+declare const OPTIONS_SYMBOL: unique symbol;
+export declare function queryOptions<T extends object>(opts: T): T & {
+    [OPTIONS_SYMBOL]: true;
+};
+export declare function createHooks<Api extends Record<string, {
+    input: any;
+    output: any;
+}>>(config: CreateHooksConfig<Api>): {
+    readonly useQuery: <Name extends ExtractNames<Api>>(...args: QueryInput<Api, Name> extends never ? [name: Name, options?: Omit<TanstackUseQueryOptions<QueryOutput<Api, Name>, HttpError, QueryOutput<Api, Name>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined] : [name: Name, input: QueryInput<Api, Name>, options?: Omit<TanstackUseQueryOptions<QueryOutput<Api, Name>, HttpError, QueryOutput<Api, Name>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined]) => UseQueryResult<QueryOutput<Api, Name>, HttpError>;
+    readonly useMutation: <Name extends ExtractNames<Api>>(name: Name, options?: Omit<TanstackUseMutationOptions<QueryOutput<Api, Name>, HttpError, QueryInput<Api, Name>, unknown>, "mutationFn">) => UseMutationResult<QueryOutput<Api, Name>, HttpError, QueryInput<Api, Name>>;
+};
+export {};
+//# sourceMappingURL=createHooks.d.ts.map

package/dist/createHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHooks.d.ts","sourceRoot":"","sources":["../src/createHooks.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,IAAI,uBAAuB,EAC/C,KAAK,kBAAkB,IAAI,0BAA0B,EACrD,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAE/D,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AACpD,KAAK,YAAY,GAAG,SAAS,GAAG,CAAC,MAAM,SAAS,CAAC,CAAC;AAElD,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,QAAA,MAAM,cAAc,eAAkC,CAAC;AAEvD,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAEtF;AAqGD,wBAAgB,WAAW,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,EACjF,MAAM,EAAE,iBAAiB,CAAC,GAAG,CAAC;wBAoFZ,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,+kBAE7C,cAAc,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC;2BAwC/B,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,QAC3C,IAAI,kIAET,iBAAiB,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;EAW/E"}

package/dist/createHooks.js

@@ -0,0 +1,177 @@
+import { useQuery as useTanstackQuery, useMutation as useTanstackMutation, } from '@tanstack/react-query';
+import { HttpError } from './errors.js';
+const OPTIONS_SYMBOL = Symbol.for('hypequery-options');
+export function queryOptions(opts) {
+    return { ...opts, [OPTIONS_SYMBOL]: true };
+}
+const normalizeMethodConfig = (source) => {
+    if (!source)
+        return {};
+    return Object.fromEntries(Object.entries(source).map(([key, value]) => [key, { method: value.method ?? 'GET', path: value.path }]));
+};
+const deriveMethodConfig = (api) => {
+    if (typeof api !== 'object' || api === null) {
+        return {};
+    }
+    // Preferred: the serve API exposes a manifest() with full method + path.
+    if (typeof api.manifest === 'function') {
+        const manifest = api.manifest();
+        if (manifest && typeof manifest === 'object') {
+            return normalizeMethodConfig(manifest);
+        }
+    }
+    if ('_routeConfig' in api &&
+        typeof api._routeConfig === 'object' &&
+        api._routeConfig !== null) {
+        return normalizeMethodConfig(api._routeConfig);
+    }
+    if ('queries' in api &&
+        typeof api.queries === 'object' &&
+        api.queries !== null) {
+        return normalizeMethodConfig(api.queries);
+    }
+    return {};
+};
+const isAbsoluteHttpUrl = (value) => /^https?:\/\//.test(value);
+const ensureTrailingSlash = (value) => value.endsWith('/') ? value : `${value}/`;
+const buildUrl = (baseUrl, name, path) => {
+    if (path) {
+        if (isAbsoluteHttpUrl(path)) {
+            return path;
+        }
+        if (isAbsoluteHttpUrl(baseUrl)) {
+            return new URL(path, ensureTrailingSlash(baseUrl)).toString();
+        }
+        if (path.startsWith('/')) {
+            return path;
+        }
+        if (!baseUrl) {
+            throw new Error('baseUrl is required');
+        }
+        return `${ensureTrailingSlash(baseUrl)}${path}`;
+    }
+    if (!baseUrl) {
+        throw new Error('baseUrl is required');
+    }
+    return `${ensureTrailingSlash(baseUrl)}${name}`;
+};
+const parseResponse = async (res) => {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+const isOptionsBag = (value) => {
+    return Boolean(value && typeof value === 'object' && OPTIONS_SYMBOL in value);
+};
+const looksLikeQueryOptions = (value) => {
+    if (isOptionsBag(value))
+        return true;
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const optionKeys = ['enabled', 'staleTime', 'gcTime', 'refetchInterval', 'refetchOnWindowFocus', 'retry', 'retryDelay'];
+    const matches = optionKeys.filter((key) => key in value).length;
+    return matches >= 2;
+};
+const resolveHeaders = (headers) => {
+    if (!headers)
+        return {};
+    const raw = typeof headers === 'function' ? headers() : headers;
+    return Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== undefined));
+};
+export function createHooks(config) {
+    const { baseUrl, fetchFn = fetch, headers = {}, config: explicitConfig = {}, manifest, api } = config;
+    // Precedence: explicit config > manifest > derived from a runtime api object.
+    const finalConfig = {
+        ...deriveMethodConfig(api),
+        ...(manifest ? normalizeMethodConfig(manifest) : {}),
+        ...explicitConfig,
+    };
+    const fetchQuery = async (name, input, defaultMethod = 'GET') => {
+        const methodConfig = finalConfig[name];
+        // Semantic endpoints (dataset:<name>) live at paths that differ from their
+        // map key, so without a resolved path we'd call the wrong URL. Fail loudly
+        // instead of silently requesting `${baseUrl}/dataset:<name>`.
+        if (name.includes(':') && !methodConfig?.path) {
+            throw new Error(`No route configured for "${name}". Pass \`manifest\` (from the serve ` +
+                `api.manifest()) or an explicit \`config\` entry to createHooks().`);
+        }
+        const url = buildUrl(baseUrl, name, methodConfig?.path);
+        const method = methodConfig?.method ?? defaultMethod;
+        let finalUrl = url;
+        let body;
+        if (method === 'GET' && input && typeof input === 'object') {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(input)) {
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value)) {
+                    value.forEach((item) => params.append(key, String(item)));
+                }
+                else {
+                    params.append(key, String(value));
+                }
+            }
+            const queryString = params.toString();
+            finalUrl = queryString ? `${url}?${queryString}` : url;
+        }
+        else if (input !== undefined) {
+            body = JSON.stringify(input);
+        }
+        const resolvedHeaders = resolveHeaders(headers);
+        const res = await fetchFn(finalUrl, {
+            method,
+            headers: {
+                ...resolvedHeaders,
+                ...(body ? { 'content-type': 'application/json' } : {}),
+            },
+            body,
+        });
+        if (!res.ok) {
+            const errorBody = await parseResponse(res);
+            throw new HttpError(`${method} request to ${finalUrl} failed with status ${res.status}`, res.status, errorBody);
+        }
+        return res.json();
+    };
+    function useQuery(...args) {
+        const [name, potentialInputOrOptions, maybeOptions] = args;
+        let input;
+        let options;
+        if (args.length === 1) {
+            input = undefined;
+            options = undefined;
+        }
+        else if (args.length === 2 && looksLikeQueryOptions(potentialInputOrOptions)) {
+            input = undefined;
+            options = potentialInputOrOptions;
+        }
+        else {
+            input = potentialInputOrOptions;
+            options = maybeOptions;
+        }
+        const queryKey = (() => {
+            if (input === undefined) {
+                return ['hypequery', name];
+            }
+            return ['hypequery', name, input];
+        })();
+        return useTanstackQuery({
+            queryKey,
+            queryFn: () => fetchQuery(name, input),
+            ...(options ?? {}),
+        });
+    }
+    function useMutation(name, options) {
+        return useTanstackMutation({
+            mutationFn: (input) => fetchQuery(name, input, 'POST'),
+            ...options,
+        });
+    }
+    return {
+        useQuery,
+        useMutation,
+    };
+}

package/dist/createHooks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createHooks.test.d.ts.map

package/dist/createHooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createHooks.test.d.ts","sourceRoot":"","sources":["../src/createHooks.test.tsx"],"names":[],"mappings":""}