fauxy 0.0.1-alpha.2 → 0.0.1-alpha.4

package/Taskfile.yaml

@@ -10,25 +10,25 @@ tasks:
   build:
     desc: "Build Docker image"
     cmds:
-      - docker build --no-cache -t playground-vapimock182 .
+      - docker build --no-cache -t fauxy .
 
   down:
     desc: "Stop and remove playground container"
     cmds:
-      - docker stop playground-vapimock182-app
-      - docker rm playground-vapimock182-app
+      - docker stop fauxy-app
+      - docker rm fauxy-app
 
   up:
     desc: "Start playground container"
     cmds:
-      - docker start playground-vapimock182-app || docker run -d --name playground-vapimock182-app -p 5173:5173 -v ${PWD}:/app playground-vapimock182
+      - docker start fauxy-app || docker run -d --name fauxy-app -p 5173:5173 -v ${PWD}:/app fauxy
 
   logs:
     desc: "Follow logs from the playground container with tail output"
     cmds:
-      - docker logs -f --tail 100 playground-vapimock182-app
+      - docker logs -f --tail 100 fauxy-app
 
   bash:
     desc: "Open interactive shell session inside the running playground container"
     cmds:
-      - docker exec -it playground-vapimock182-app sh
+      - docker exec -it fauxy-app sh

package/docs/laravel-mix.md

@@ -0,0 +1,54 @@
+# Using Fauxy with Laravel Mix
+
+This section demonstrates how to integrate Fauxy into a project using Laravel Mix, ensuring that all mock-related code
+does not end up in production. This was particularly important for me, as supporting very old browser versions was
+challenging.
+
+> **Note:** This is just an example setup to demonstrate how Fauxy can be integrated with Laravel Mix.
+> It is not meant to be a production-ready configuration, and some parts of the code are simplified for illustrative purposes.
+> Adjust it according to your project's requirements and best practices.
+
+First, create a file, for example, `resources/ts/mock.ts`, and initialize Fauxy there.
+
+Next, add the following code to your `webpack.mix.js`:
+
+```js
+const mockSrc = process.env.MIX_MOCK_API === 'true' ? ['resources/ts/mock.ts'] : [];
+
+mix
+  .ts([
+    ...mockSrc,
+    'resources/ts/vue.ts'
+  ], 'public/js/vue.js')
+```
+
+In this example, I use Vue. Since the `mock.ts` and `vue.ts` files are added to the build independently, it’s important to
+ensure that the code from `mock.ts` runs first. The simplest way to achieve this is:
+
+```ts
+// mock.ts
+import { mockApi } from 'fauxy'
+import someHandlers from '@/mocks/handlers/some-handlers'
+
+window.MOCK_SETUP = {
+  startMock: async () => {
+    return mockApi([...someHandlers])
+  },
+}
+```
+
+```ts
+// vue.ts
+import Vue from 'vue'
+
+const initApp = async () => {
+  if (window?.MOCK_SETUP?.startMock) {
+    await window.MOCK_SETUP?.startMock()
+  }
+
+  return new Vue({
+    el: '#app',
+    pinia,
+  })
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxy",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.4",
   "description": "A package for mocking data and API requests",
   "license": "MIT",
   "homepage": "https://github.com/heavenlybilly/fauxy",

package/readme.md

@@ -1,32 +1,25 @@
 # Fauxy
-description
 
-## Содержание
-- [Начало работы](#начало-работы)
+Fauxy is a lightweight wrapper around **faker.js** and **MSW** (Mock Service Worker), designed to simplify mocking data
+and API requests for both front-end and back-end development. MSW is used as-is (imported directly from the package),
+while Faker is wrapped with a special API that adds some convenience helpers and customizations. I created Fauxy
+primarily for my own convenience, but I hope it can be useful to others as well.
 
-## Начало работы
+## Features
 
-#### Установка пакета
-```bash
-npm i fauxy
-```
-
-#### Настройка окружения
-1. Для добавления Mock API в Laravel Mix, необходимо добавить новый файл, например, `resources/ts/mock.ts` с содержимым:
-```ts
-import { mockApi } from 'fauxy'
+- Simple API for generating mock data using a wrapped version of **faker.js** with additional helpers.
+- Built-in **MSW** integration to mock API requests.
+- Ready-to-use mock service worker file for front-end development.
+- Lightweight and easy to set up.
 
-mockApi.start()
-```
+## Installation
 
-2. Изменить файл `package.json`:
-```json
-"scripts": {
-    "watch:msw": "MIX_MOCK_API=true mix watch",
-},
+```bash
+npm install fauxy
+npx fauxy init
 ```
 
-Добавить в конец файла:
+To ensure MSW knows where to find the service worker, add the following section to your package.json:
 ```json
 "msw": {
   "workerDirectory": [
@@ -35,13 +28,18 @@ mockApi.start()
 }
 ```
 
-3. В файле `webpack.mix.js` добавить в сборку файл `mock.ts` (из п.1):
-```js
-const mockSrc = process.env.MIX_MOCK_API === 'true' ? ['resources/ts/mock.ts'] : [];
+An example of starting the mock service worker:
+```ts
+import { mockApi } from 'fauxy'
+
+mockApi.start()
+```
+
+## How to use ![WIP](https://img.shields.io/badge/status-WIP-yellow)
+
+- [Laravel Mix](docs/laravel-mix.md)
 
-mix
-  .ts([
-    ...mockSrc,
-    'resources/ts/vue.ts'
-  ], 'public/js/vue.js')
-```
+## Notes
+- Fauxy uses MSW directly from its package, so you can access all MSW features as usual.
+- Faker is only available via Fauxy’s wrapper, which adds convenience methods and some custom enhancements.
+- For more advanced usage and configuration, check out the official MSW repository.

package/scripts/init.cjs

@@ -9,12 +9,17 @@ const colors = {
   reset: '\x1b[0m'
 };
 
-const sourceSwPath = path.join(__dirname, '../node_modules/msw/lib/mockServiceWorker.js');
+const sourceSwPath = path.join(__dirname, './mockServiceWorker.js');
 const targetSwPath = path.join(process.cwd(), 'public/mockServiceWorker.js');
 
+console.warn(
+  '\x1b[33m⚠️  This package uses MSW (https://github.com/mswjs/msw). ' +
+  'For more details and advanced usage, please visit the official repository.\x1b[0m'
+);
+
 try {
   if (!fs.existsSync(sourceSwPath)) {
-    console.error(colors.error + '❌ Mock Service Worker not found' + colors.reset);
+    console.error(colors.error + '❌  mockServiceWorker.js not found' + colors.reset);
     process.exit(0);
   }
 
@@ -24,9 +29,9 @@ try {
   }
 
   fs.copyFileSync(sourceSwPath, targetSwPath);
-  console.log(colors.success + '✅ Mock Service Worker copied to public/' + colors.reset);
+  console.log(colors.success + '✅  Mock Service Worker copied to public/' + colors.reset);
 
 } catch (error) {
-  console.error(colors.error + '❌ Failed to copy Mock Service Worker:' + colors.reset);
+  console.error(colors.error + '❌  Failed to copy Mock Service Worker:' + colors.reset);
   console.error(colors.error + error.message + colors.reset);
 }

package/scripts/mockServiceWorker.js

@@ -0,0 +1,349 @@
+/* eslint-disable */
+/* tslint:disable */
+
+/**
+ * Mock Service Worker.
+ * @see https://github.com/mswjs/msw
+ * - Please do NOT modify this file.
+ */
+
+const PACKAGE_VERSION = '2.12.0'
+const INTEGRITY_CHECKSUM = '4db4a41e972cec1b64cc569c66952d82'
+const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
+const activeClientIds = new Set()
+
+addEventListener('install', function () {
+  self.skipWaiting()
+})
+
+addEventListener('activate', function (event) {
+  event.waitUntil(self.clients.claim())
+})
+
+addEventListener('message', async function (event) {
+  const clientId = Reflect.get(event.source || {}, 'id')
+
+  if (!clientId || !self.clients) {
+    return
+  }
+
+  const client = await self.clients.get(clientId)
+
+  if (!client) {
+    return
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  switch (event.data) {
+    case 'KEEPALIVE_REQUEST': {
+      sendToClient(client, {
+        type: 'KEEPALIVE_RESPONSE',
+      })
+      break
+    }
+
+    case 'INTEGRITY_CHECK_REQUEST': {
+      sendToClient(client, {
+        type: 'INTEGRITY_CHECK_RESPONSE',
+        payload: {
+          packageVersion: PACKAGE_VERSION,
+          checksum: INTEGRITY_CHECKSUM,
+        },
+      })
+      break
+    }
+
+    case 'MOCK_ACTIVATE': {
+      activeClientIds.add(clientId)
+
+      sendToClient(client, {
+        type: 'MOCKING_ENABLED',
+        payload: {
+          client: {
+            id: client.id,
+            frameType: client.frameType,
+          },
+        },
+      })
+      break
+    }
+
+    case 'CLIENT_CLOSED': {
+      activeClientIds.delete(clientId)
+
+      const remainingClients = allClients.filter((client) => {
+        return client.id !== clientId
+      })
+
+      // Unregister itself when there are no more clients
+      if (remainingClients.length === 0) {
+        self.registration.unregister()
+      }
+
+      break
+    }
+  }
+})
+
+addEventListener('fetch', function (event) {
+  const requestInterceptedAt = Date.now()
+
+  // Bypass navigation requests.
+  if (event.request.mode === 'navigate') {
+    return
+  }
+
+  // Opening the DevTools triggers the "only-if-cached" request
+  // that cannot be handled by the worker. Bypass such requests.
+  if (
+    event.request.cache === 'only-if-cached' &&
+    event.request.mode !== 'same-origin'
+  ) {
+    return
+  }
+
+  // Bypass all requests when there are no active clients.
+  // Prevents the self-unregistered worked from handling requests
+  // after it's been terminated (still remains active until the next reload).
+  if (activeClientIds.size === 0) {
+    return
+  }
+
+  const requestId = crypto.randomUUID()
+  event.respondWith(handleRequest(event, requestId, requestInterceptedAt))
+})
+
+/**
+ * @param {FetchEvent} event
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ */
+async function handleRequest(event, requestId, requestInterceptedAt) {
+  const client = await resolveMainClient(event)
+  const requestCloneForEvents = event.request.clone()
+  const response = await getResponse(
+    event,
+    client,
+    requestId,
+    requestInterceptedAt,
+  )
+
+  // Send back the response clone for the "response:*" life-cycle events.
+  // Ensure MSW is active and ready to handle the message, otherwise
+  // this message will pend indefinitely.
+  if (client && activeClientIds.has(client.id)) {
+    const serializedRequest = await serializeRequest(requestCloneForEvents)
+
+    // Clone the response so both the client and the library could consume it.
+    const responseClone = response.clone()
+
+    sendToClient(
+      client,
+      {
+        type: 'RESPONSE',
+        payload: {
+          isMockedResponse: IS_MOCKED_RESPONSE in response,
+          request: {
+            id: requestId,
+            ...serializedRequest,
+          },
+          response: {
+            type: responseClone.type,
+            status: responseClone.status,
+            statusText: responseClone.statusText,
+            headers: Object.fromEntries(responseClone.headers.entries()),
+            body: responseClone.body,
+          },
+        },
+      },
+      responseClone.body ? [serializedRequest.body, responseClone.body] : [],
+    )
+  }
+
+  return response
+}
+
+/**
+ * Resolve the main client for the given event.
+ * Client that issues a request doesn't necessarily equal the client
+ * that registered the worker. It's with the latter the worker should
+ * communicate with during the response resolving phase.
+ * @param {FetchEvent} event
+ * @returns {Promise<Client | undefined>}
+ */
+async function resolveMainClient(event) {
+  const client = await self.clients.get(event.clientId)
+
+  if (activeClientIds.has(event.clientId)) {
+    return client
+  }
+
+  if (client?.frameType === 'top-level') {
+    return client
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  return allClients
+    .filter((client) => {
+      // Get only those clients that are currently visible.
+      return client.visibilityState === 'visible'
+    })
+    .find((client) => {
+      // Find the client ID that's recorded in the
+      // set of clients that have registered the worker.
+      return activeClientIds.has(client.id)
+    })
+}
+
+/**
+ * @param {FetchEvent} event
+ * @param {Client | undefined} client
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ * @returns {Promise<Response>}
+ */
+async function getResponse(event, client, requestId, requestInterceptedAt) {
+  // Clone the request because it might've been already used
+  // (i.e. its body has been read and sent to the client).
+  const requestClone = event.request.clone()
+
+  function passthrough() {
+    // Cast the request headers to a new Headers instance
+    // so the headers can be manipulated with.
+    const headers = new Headers(requestClone.headers)
+
+    // Remove the "accept" header value that marked this request as passthrough.
+    // This prevents request alteration and also keeps it compliant with the
+    // user-defined CORS policies.
+    const acceptHeader = headers.get('accept')
+    if (acceptHeader) {
+      const values = acceptHeader.split(',').map((value) => value.trim())
+      const filteredValues = values.filter(
+        (value) => value !== 'msw/passthrough',
+      )
+
+      if (filteredValues.length > 0) {
+        headers.set('accept', filteredValues.join(', '))
+      } else {
+        headers.delete('accept')
+      }
+    }
+
+    return fetch(requestClone, { headers })
+  }
+
+  // Bypass mocking when the client is not active.
+  if (!client) {
+    return passthrough()
+  }
+
+  // Bypass initial page load requests (i.e. static assets).
+  // The absence of the immediate/parent client in the map of the active clients
+  // means that MSW hasn't dispatched the "MOCK_ACTIVATE" event yet
+  // and is not ready to handle requests.
+  if (!activeClientIds.has(client.id)) {
+    return passthrough()
+  }
+
+  // Notify the client that a request has been intercepted.
+  const serializedRequest = await serializeRequest(event.request)
+  const clientMessage = await sendToClient(
+    client,
+    {
+      type: 'REQUEST',
+      payload: {
+        id: requestId,
+        interceptedAt: requestInterceptedAt,
+        ...serializedRequest,
+      },
+    },
+    [serializedRequest.body],
+  )
+
+  switch (clientMessage.type) {
+    case 'MOCK_RESPONSE': {
+      return respondWithMock(clientMessage.data)
+    }
+
+    case 'PASSTHROUGH': {
+      return passthrough()
+    }
+  }
+
+  return passthrough()
+}
+
+/**
+ * @param {Client} client
+ * @param {any} message
+ * @param {Array<Transferable>} transferrables
+ * @returns {Promise<any>}
+ */
+function sendToClient(client, message, transferrables = []) {
+  return new Promise((resolve, reject) => {
+    const channel = new MessageChannel()
+
+    channel.port1.onmessage = (event) => {
+      if (event.data && event.data.error) {
+        return reject(event.data.error)
+      }
+
+      resolve(event.data)
+    }
+
+    client.postMessage(message, [
+      channel.port2,
+      ...transferrables.filter(Boolean),
+    ])
+  })
+}
+
+/**
+ * @param {Response} response
+ * @returns {Response}
+ */
+function respondWithMock(response) {
+  // Setting response status code to 0 is a no-op.
+  // However, when responding with a "Response.error()", the produced Response
+  // instance will have status code set to 0. Since it's not possible to create
+  // a Response instance with status code 0, handle that use-case separately.
+  if (response.status === 0) {
+    return Response.error()
+  }
+
+  const mockedResponse = new Response(response.body, response)
+
+  Reflect.defineProperty(mockedResponse, IS_MOCKED_RESPONSE, {
+    value: true,
+    enumerable: true,
+  })
+
+  return mockedResponse
+}
+
+/**
+ * @param {Request} request
+ */
+async function serializeRequest(request) {
+  return {
+    url: request.url,
+    mode: request.mode,
+    method: request.method,
+    headers: Object.fromEntries(request.headers.entries()),
+    cache: request.cache,
+    credentials: request.credentials,
+    destination: request.destination,
+    integrity: request.integrity,
+    redirect: request.redirect,
+    referrer: request.referrer,
+    referrerPolicy: request.referrerPolicy,
+    body: await request.arrayBuffer(),
+    keepalive: request.keepalive,
+  }
+}