openapi-ff 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Oleg Borodatov
+
+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,119 @@
+# openapi-ff
+
+openapi-ff is a type-safe tiny wrapper around [effector](https://effector.dev/) and [farfetched](https://ff.effector.dev/) to work with OpenAPI schema.
+
+It works by using [openapi-fetch](../openapi-fetch) and [openapi-typescript](../openapi-typescript).
+
+## Setup
+
+```bash
+pnpm i openapi-ff @farfetched/core effector openapi-fetch
+pnpm i -D openapi-typescript typescript
+```
+
+Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
+
+```bash
+npx openapi-typescript ./path/to/api/v1.yaml -o ./src/shared/api/schema.d.ts
+```
+
+## Usage
+
+```ts
+import createFetchClient from "openapi-fetch";
+import { createClient } from "openapi-ff";
+import { createQuery } from "@farfetched/core";
+import type { paths } from "./schema"; // generated by openapi-typescript
+
+export const client = createFetchClient<paths>({
+  baseUrl: "https://myapi.dev/v1/",
+});
+export const { createApiEffect } = createClient(client);
+
+const blogpostQuery = createQuery({
+  effect: createApiEffect("get", "/blogposts/{post_id}"),
+});
+```
+
+```tsx
+import { useUnit } from "effector-react";
+
+function Post() {
+  const { data: post, pending } = useUnit(blogpostQuery);
+
+  if (pending) {
+    return <Loader />;
+  }
+
+  return (
+    <section>
+      <p>{post.title}</p>
+    </section>
+  );
+}
+```
+
+Advanced Usage:
+
+```ts
+import { chainRoute } from "atomic-router";
+import { startChain } from "@farfetched/atomic-router";
+
+const getBlogpostFx = createApiEffect("get", "/blogposts/{post_id}", {
+  mapParams: (args: { postId: string }) => ({ params: { path: { post_id: args.postId } } }),
+});
+const blogpostQuery = createQuery({
+  effect: getBlogpostFx,
+  mapData: ({ result, params }) => ({ ...result, ...params }),
+  initialData: { body: "-", title: "-", postId: "0" },
+});
+
+export const blogpostRoute = chainRoute({
+  route: routes.blogpost.item,
+  ...startChain(blogpostQuery),
+});
+
+const apiError = sample({
+  clock: softwareQuery.finished.failure,
+  filter: isApiError,
+});
+```
+
+## Runtime Validation
+
+`openapi-ff` does not handle runtime validation, as `openapi-typescript` [does not support it](https://github.com/openapi-ts/openapi-typescript/issues/1420#issuecomment-1792909086).
+
+> openapi-typescript by its design generates runtime-free static types, and only static types.
+
+To enable runtime validation, you can use third-party solutions, such as **[orval](https://orval.dev/)**:
+
+```bash
+pnpm install zod @farfetched/zod
+npx orval --input path/to/api.yaml --output src/zod.ts --client zod --mode single
+```
+
+Usage:
+
+```ts
+import { zodContract } from "@farfetched/zod";
+import { getBlogpostsResponseItem } from "./zod";
+
+const blogpostQuery = createQuery({
+  effect: createApiEffect("get", "/blogposts/{post_id}"),
+  contract: zodContract(getBlogpostsResponseItem),
+});
+```
+
+## TODO
+
+Add `createApiQuery`:
+
+```ts
+createApiQuery({
+  method: "get",
+  path: "/blogposts/{post_id}",
+  mapParams: (args: { postId: string }) => ({ params: { path: { post_id: args.postId } } }),
+  mapData: ({ result, params }) => ({ ...result, ...params }),
+  initialData: { body: "-", title: "-", postId: "0" },
+});
+```

package/dist/openapi-ff.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("effector"),o=require("@farfetched/core"),f="API";function w(r){return{...r,errorType:f,explanation:"Request was finished with unsuccessful HTTP code"}}function E(r){var s;return((s=r.error)==null?void 0:s.errorType)===f}function d(r){return{createApiEffect:(s,i,e)=>{const l=s.toUpperCase(),T=r[l];return p.createEffect(async u=>{var c;const{data:h,error:a,response:t}=await T(i,((c=e==null?void 0:e.mapParams)==null?void 0:c.call(e,u))??u).catch(n=>{throw o.networkError({reason:(n==null?void 0:n.message)??null,cause:n})});if(a!=null&&a!=="")throw w({status:t.status,statusText:t.statusText,response:a});if(!t.ok)throw o.httpError({status:t.status,statusText:t.statusText,response:null});return h})}}}exports.createClient=d;exports.isApiError=E;

package/dist/openapi-ff.d.cts

@@ -0,0 +1,42 @@
+import { Client } from 'openapi-fetch';
+import { Effect } from 'effector';
+import { FarfetchedError } from '@farfetched/core';
+import { FetchResponse } from 'openapi-fetch';
+import { HttpError } from '@farfetched/core';
+import { HttpMethod } from 'openapi-typescript-helpers';
+import { MaybeOptionalInit } from 'openapi-fetch';
+import { MediaType } from 'openapi-typescript-helpers';
+import { NetworkError } from '@farfetched/core';
+import { PathsWithMethod } from 'openapi-typescript-helpers';
+
+declare const API = "API";
+
+export declare interface ApiError<Status extends number = number, ApiResponse = unknown> extends FarfetchedError<typeof API> {
+    status: Status;
+    statusText: string;
+    response: ApiResponse;
+}
+
+declare type CreateApiEffect<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, Options extends CreateApiEffectOptions<Init> = {}>(method: Method, path: Path, options?: Options) => Effect<Init extends undefined ? void : InitOrPrependInit<Init, Parameters<NonNullable<Options["mapParams"]>>[0], Options>, Response["data"], ApiError<number, Response["error"]> | HttpError | NetworkError>;
+
+declare type CreateApiEffectOptions<Init> = {
+    mapParams?: (init: any) => Init;
+};
+
+export declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: Client<Paths, Media>): OpenapiEffectorClient<Paths, Media>;
+
+declare type InitOrPrependInit<Init, PrependInit, Options extends CreateApiEffectOptions<Init>> = Options extends {
+    mapParams: (init: any) => any;
+} ? PrependInit : Init;
+
+export declare function isApiError(args: WithError): args is WithError<ApiError>;
+
+declare interface OpenapiEffectorClient<Paths extends {}, Media extends MediaType = MediaType> {
+    createApiEffect: CreateApiEffect<Paths, Media>;
+}
+
+declare type WithError<T = any, P = Record<string, unknown>> = P & {
+    error: T;
+};
+
+export { }

package/dist/openapi-ff.d.ts

@@ -0,0 +1,42 @@
+import { Client } from 'openapi-fetch';
+import { Effect } from 'effector';
+import { FarfetchedError } from '@farfetched/core';
+import { FetchResponse } from 'openapi-fetch';
+import { HttpError } from '@farfetched/core';
+import { HttpMethod } from 'openapi-typescript-helpers';
+import { MaybeOptionalInit } from 'openapi-fetch';
+import { MediaType } from 'openapi-typescript-helpers';
+import { NetworkError } from '@farfetched/core';
+import { PathsWithMethod } from 'openapi-typescript-helpers';
+
+declare const API = "API";
+
+export declare interface ApiError<Status extends number = number, ApiResponse = unknown> extends FarfetchedError<typeof API> {
+    status: Status;
+    statusText: string;
+    response: ApiResponse;
+}
+
+declare type CreateApiEffect<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, Options extends CreateApiEffectOptions<Init> = {}>(method: Method, path: Path, options?: Options) => Effect<Init extends undefined ? void : InitOrPrependInit<Init, Parameters<NonNullable<Options["mapParams"]>>[0], Options>, Response["data"], ApiError<number, Response["error"]> | HttpError | NetworkError>;
+
+declare type CreateApiEffectOptions<Init> = {
+    mapParams?: (init: any) => Init;
+};
+
+export declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: Client<Paths, Media>): OpenapiEffectorClient<Paths, Media>;
+
+declare type InitOrPrependInit<Init, PrependInit, Options extends CreateApiEffectOptions<Init>> = Options extends {
+    mapParams: (init: any) => any;
+} ? PrependInit : Init;
+
+export declare function isApiError(args: WithError): args is WithError<ApiError>;
+
+declare interface OpenapiEffectorClient<Paths extends {}, Media extends MediaType = MediaType> {
+    createApiEffect: CreateApiEffect<Paths, Media>;
+}
+
+declare type WithError<T = any, P = Record<string, unknown>> = P & {
+    error: T;
+};
+
+export { }

package/dist/openapi-ff.js

@@ -0,0 +1,50 @@
+import { createEffect as p } from "effector";
+import { networkError as T, httpError as i } from "@farfetched/core";
+const f = "API";
+function w(r) {
+  return {
+    ...r,
+    errorType: f,
+    explanation: "Request was finished with unsuccessful HTTP code"
+  };
+}
+function A(r) {
+  var s;
+  return ((s = r.error) == null ? void 0 : s.errorType) === f;
+}
+function P(r) {
+  return {
+    createApiEffect: (s, c, t) => {
+      const l = s.toUpperCase(), h = r[l];
+      return p(async (u) => {
+        var o;
+        const { data: m, error: n, response: e } = await h(
+          c,
+          ((o = t == null ? void 0 : t.mapParams) == null ? void 0 : o.call(t, u)) ?? u
+        ).catch((a) => {
+          throw T({
+            reason: (a == null ? void 0 : a.message) ?? null,
+            cause: a
+          });
+        });
+        if (n != null && n !== "")
+          throw w({
+            status: e.status,
+            statusText: e.statusText,
+            response: n
+          });
+        if (!e.ok)
+          throw i({
+            status: e.status,
+            statusText: e.statusText,
+            response: null
+          });
+        return m;
+      });
+    }
+  };
+}
+export {
+  P as createClient,
+  A as isApiError
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "openapi-ff",
+  "version": "0.1.0",
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --typecheck",
+    "build": "vite build",
+    "format": "biome format --write ./src",
+    "lint": "biome check --apply ./src"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/openapi-ff.cjs",
+  "module": "./dist/openapi-ff.js",
+  "types": "./dist/openapi-ff.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/openapi-ff.d.ts",
+        "default": "./dist/openapi-ff.js"
+      },
+      "require": {
+        "types": "./dist/openapi-ff.d.cts",
+        "default": "./dist/openapi-ff.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^20.12.7",
+    "typescript": "5.1.6",
+    "undici": "^6.21.0",
+    "vite": "5",
+    "vite-plugin-dts": "^3.8.3",
+    "vite-tsconfig-paths": "4.2.1",
+    "vitest": "2.0.4"
+  },
+  "peerDependencies": {
+    "@farfetched/core": "^0.12.8",
+    "effector": "^23.2.3"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.13.0",
+    "openapi-typescript-helpers": "^0.0.15"
+  }
+}