katanakit-js 2.2.1 → 2.12.9

package/dist/core/services/http.service.d.ts

@@ -1,22 +1,245 @@
-import type { ApisConfig, FetchOptions, FetchResult, IFetchApiManager, UrlOptions } from "../../types/index.js";
-/**
- * Framework-agnostic HTTP client: builds safe URLs from a JSON-defined registry
- * and wraps `fetch` in a Safe Result. Implemented as a Facade + Singleton.
- */
-export declare class FetchApiManager implements IFetchApiManager {
-    private static instance;
-    private apis;
-    private constructor();
-    static getInstance(): FetchApiManager;
-    useInit: (apis: ApisConfig) => void;
-    useGetApis: () => ApisConfig;
-    private GET_API_ENTRY;
-    useBuildUrl: (apiName: string, endpointName: string, options?: UrlOptions) => string;
-    useFetch: <T = unknown>(apiName: string, endpointName: string, { urlOptions, ...init }?: FetchOptions) => Promise<FetchResult<T>>;
-    useGet: <T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions) => Promise<FetchResult<T>>;
-    usePost: <T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions) => Promise<FetchResult<T>>;
-    usePut: <T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions) => Promise<FetchResult<T>>;
-    useDelete: <T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions) => Promise<FetchResult<T>>;
-}
-export declare const useFetch: <T = unknown>(apiName: string, endpointName: string, { urlOptions, ...init }?: FetchOptions) => Promise<FetchResult<T>>, useGetApis: () => ApisConfig, useInit: (apis: ApisConfig) => void, useGet: <T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions) => Promise<FetchResult<T>>, usePost: <T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions) => Promise<FetchResult<T>>, useDelete: <T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions) => Promise<FetchResult<T>>, usePut: <T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions) => Promise<FetchResult<T>>, useBuildUrl: (apiName: string, endpointName: string, options?: UrlOptions) => string;
+import type { ApisConfig, FetchOptions, FetchResult, UrlOptions } from "../../types/index.js";
+/**
+ * Registers (merges) API definitions into the client registry.
+ * Prefer the clearer alias {@link useInitApis}.
+ *
+ * @param apisConfig - The API definitions to merge into the registry.
+ *
+ * @example
+ * ```ts
+ * import { useInit } from "katanakit-js";
+ *
+ * useInit({
+ *   pokeapi: {
+ *     baseUri: "https://pokeapi.co/api/v2",
+ *     endpoints: { pokemonById: "/pokemon/:id/" },
+ *   },
+ * });
+ * ```
+ */
+export declare function useInit(apisConfig: ApisConfig): void;
+/**
+ * Registers (merges) API definitions into the client registry.
+ *
+ * @param apisConfig - The API definitions to merge into the registry.
+ *
+ * @example
+ * ```ts
+ * import { useInitApis } from "katanakit-js";
+ *
+ * useInitApis({
+ *   pokeapi: {
+ *     baseUri: "https://pokeapi.co/api/v2",
+ *     endpoints: { pokemonById: "/pokemon/:id/" },
+ *   },
+ * });
+ * ```
+ */
+export declare function useInitApis(apisConfig: ApisConfig): void;
+/**
+ * Returns a shallow copy of the registered APIs (safe to mutate locally).
+ *
+ * @returns A shallow copy of the current API registry.
+ *
+ * @example
+ * ```ts
+ * import { useGetApis } from "katanakit-js";
+ *
+ * const apis = useGetApis();
+ * ```
+ */
+export declare function useGetApis(): ApisConfig;
+/**
+ * Returns a shallow copy of the registered APIs.
+ * Alias for {@link useGetApis}.
+ *
+ * @returns A shallow copy of the current API registry.
+ *
+ * @example
+ * ```ts
+ * import { useGetApisConfig } from "katanakit-js";
+ *
+ * const apis = useGetApisConfig();
+ * ```
+ */
+export declare function useGetApisConfig(): ApisConfig;
+/**
+ * Builds a safe http(s) URL from a registered API + endpoint.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param options - Optional URL building options (params, query, ignoreDefaultQuery).
+ * @returns The fully constructed URL string.
+ * @throws {Error} If the API or endpoint is not registered, or the URL scheme is not http(s).
+ *
+ * @example
+ * ```ts
+ * import { useBuildUrl } from "katanakit-js";
+ *
+ * const url = useBuildUrl("pokeapi", "pokemonById", { params: { id: 25 } });
+ * ```
+ */
+export declare function useBuildUrl(apiName: string, endpointName: string, options?: UrlOptions): string;
+/**
+ * Builds a safe http(s) URL from a registered API + endpoint.
+ * Alias for {@link useBuildUrl}.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param options - Optional URL building options.
+ * @returns The fully constructed URL string.
+ *
+ * @example
+ * ```ts
+ * import { useBuildApiUrl } from "katanakit-js";
+ *
+ * const url = useBuildApiUrl("pokeapi", "pokemonById", { params: { id: 25 } });
+ * ```
+ */
+export declare function useBuildApiUrl(apiName: string, endpointName: string, options?: UrlOptions): string;
+/**
+ * Fetches a registered endpoint and returns a Safe Result.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param options - Optional fetch options (method, headers, body, urlOptions).
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { useFetch } from "katanakit-js";
+ *
+ * const result = await useFetch("pokeapi", "pokemonById", {
+ *   method: "GET",
+ *   urlOptions: { params: { id: 25 } },
+ * });
+ * if (result.ok) console.log(result.data);
+ * ```
+ */
+export declare function useFetch<T = unknown>(apiName: string, endpointName: string, { urlOptions, ...init }?: FetchOptions): Promise<FetchResult<T>>;
+/**
+ * Fetches a registered endpoint and returns a Safe Result.
+ * Alias for {@link useFetch}.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param options - Optional fetch options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { useFetchApi } from "katanakit-js";
+ *
+ * const result = await useFetchApi("pokeapi", "pokemonById", {
+ *   method: "GET",
+ *   urlOptions: { params: { id: 25 } },
+ * });
+ * if (result.ok) console.log(result.data);
+ * ```
+ */
+export declare function useFetchApi<T = unknown>(apiName: string, endpointName: string, options?: FetchOptions): Promise<FetchResult<T>>;
+/**
+ * GET helper over a registered API endpoint.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param urlOptions - Optional URL building options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { useGet } from "katanakit-js";
+ *
+ * const result = await useGet<{ name: string }>("pokeapi", "pokemonById", {
+ *   params: { id: 25 },
+ * });
+ * ```
+ */
+export declare function useGet<T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions): Promise<FetchResult<T>>;
+/**
+ * GET helper over a registered API endpoint.
+ * Alias for {@link useGet}.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param urlOptions - Optional URL building options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { useGetApi } from "katanakit-js";
+ *
+ * const result = await useGetApi<{ name: string }>("pokeapi", "pokemonById", {
+ *   params: { id: 25 },
+ * });
+ * ```
+ */
+export declare function useGetApi<T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions): Promise<FetchResult<T>>;
+/**
+ * POST helper over a registered API endpoint.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param body - Optional request body (auto-serialized to JSON unless raw).
+ * @param urlOptions - Optional URL building options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { usePost } from "katanakit-js";
+ *
+ * const result = await usePost("pokeapi", "createPokemon", { name: "Pikachu" });
+ * ```
+ */
+export declare function usePost<T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions): Promise<FetchResult<T>>;
+/**
+ * PUT helper over a registered API endpoint.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param body - Optional request body (auto-serialized to JSON unless raw).
+ * @param urlOptions - Optional URL building options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { usePut } from "katanakit-js";
+ *
+ * const result = await usePut("pokeapi", "updatePokemon", { name: "Raichu" }, { params: { id: 25 } });
+ * ```
+ */
+export declare function usePut<T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions): Promise<FetchResult<T>>;
+/**
+ * PATCH helper over a registered API endpoint.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param body - Optional request body (auto-serialized to JSON unless raw).
+ * @param urlOptions - Optional URL building options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { usePatch } from "katanakit-js";
+ *
+ * const result = await usePatch("pokeapi", "updatePokemon", { name: "Raichu" }, { params: { id: 25 } });
+ * ```
+ */
+export declare function usePatch<T = unknown>(apiName: string, endpointName: string, body?: unknown, urlOptions?: UrlOptions): Promise<FetchResult<T>>;
+/**
+ * DELETE helper over a registered API endpoint.
+ *
+ * @param apiName - The registered API key.
+ * @param endpointName - The endpoint key within the API.
+ * @param urlOptions - Optional URL building options.
+ * @returns A {@link FetchResult} with data or error.
+ *
+ * @example
+ * ```ts
+ * import { useDelete } from "katanakit-js";
+ *
+ * const result = await useDelete("pokeapi", "deletePokemon", { params: { id: 25 } });
+ * ```
+ */
+export declare function useDelete<T = unknown>(apiName: string, endpointName: string, urlOptions?: UrlOptions): Promise<FetchResult<T>>;
 //# sourceMappingURL=http.service.d.ts.map

package/dist/core/services/http.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/http.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,MAAM,sBAAsB,CAAC;AAE9B;;;GAGG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACvD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkB;IACzC,OAAO,CAAC,IAAI,CAAkB;IAE9B,OAAO,eAAiB;IAExB,OAAc,WAAW,IAAI,eAAe,CAK3C;IAEM,OAAO,SAAU,UAAU,KAAG,IAAI,CAEvC;IAEK,UAAU,QAAO,UAAU,CAAc;IAEhD,OAAO,CAAC,aAAa,CAMnB;IAEK,WAAW,YAAa,MAAM,gBAAgB,MAAM,YAAW,UAAU,KAAQ,MAAM,CAuC5F;IAEK,QAAQ,GAAU,CAAC,GAAG,OAAO,WAC1B,MAAM,gBACD,MAAM,4BACK,YAAY,KACnC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoDxB;IAEK,MAAM,GAAU,CAAC,GAAG,OAAO,WACxB,MAAM,gBACD,MAAM,eACP,UAAU,KACrB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAC8C;IAEjE,OAAO,GAAU,CAAC,GAAG,OAAO,WACzB,MAAM,gBACD,MAAM,SACb,OAAO,eACD,UAAU,KACrB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAMtB;IAEG,MAAM,GAAU,CAAC,GAAG,OAAO,WACxB,MAAM,gBACD,MAAM,SACb,OAAO,eACD,UAAU,KACrB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAMtB;IAEG,SAAS,GAAU,CAAC,GAAG,OAAO,WAC3B,MAAM,gBACD,MAAM,eACP,UAAU,KACrB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAItB;CACJ;AAGD,eAAO,MACN,QAAQ,GAxGiB,CAAC,qBAChB,MAAM,gBACD,MAAM,4BACK,YAAY,8BAsGtC,UAAU,QA5Jc,UAAU,EA6JlC,OAAO,SAjKiB,UAAU,KAAG,IAAI,EAkKzC,MAAM,GAjDiB,CAAC,qBACd,MAAM,gBACD,MAAM,eACP,UAAU,8BA+CxB,OAAO,GA3CiB,CAAC,qBACf,MAAM,gBACD,MAAM,SACb,OAAO,eACD,UAAU,8BAwCxB,SAAS,GAlBiB,CAAC,qBACjB,MAAM,gBACD,MAAM,eACP,UAAU,8BAgBxB,MAAM,GAhCiB,CAAC,qBACd,MAAM,gBACD,MAAM,SACb,OAAO,eACD,UAAU,8BA6BxB,WAAW,YAxJoB,MAAM,gBAAgB,MAAM,YAAW,UAAU,KAAQ,MAyJvC,CAAC"}
+{"version":3,"file":"http.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/http.service.ts"],"names":[],"mappings":"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"}