Merge branch 'main' into patch-1

.github/pull_request_template.md

@@ -16,8 +16,8 @@
   - Add section with overloads, if have
   - Add `Motivation`, `Formulae`, `Arguments` and `Return` sections for each overload
   - Add useful examples in `Example` section for each overload
-- [ ] Add section to `README.md` in the repository root
-  - Add method to the table of contents into correct category `- [MethodName](#methodname) - description.`
-  - Add section `## MethodName`
-  - Add `[Method documentation & API](/src/method-name)` into section
-  - Add simple example
+- [ ] Fill frontmatter in `src/method-name/readme.md`
+  - Add `title`. Make sure it uses camelCase syntax just like the method itself
+  - Add `slug`. Use param-case to write it. In most cases it will be just like `title`
+  - Add `desription` with one short sentence describing what method useful for
+  - Add `group`. To categorize method on `/operators` page. Full list of available groups, you can see in [documentation/src/content/config.ts](../documentation/src/content/config.ts)

.github/workflows/docs.yml

@@ -12,15 +12,15 @@ jobs:
 
     steps:
       - name: 🛎️ Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: 📦 Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
 
-      - name: 🐧 Use Node.js v18.x
+      - name: 🐧 Use Node.js v20.x
         uses: actions/setup-node@v4
         with:
-          node-version: v18.x
+          node-version: v20.x
           cache: 'pnpm'
           cache-dependency-path: pnpm-lock.yaml
 
@@ -29,11 +29,11 @@ jobs:
         working-directory: ./
 
       - name: 🔧 Build
-        run: pnpm build
-        working-directory: ./website
+        run: pnpm doc build
+        working-directory: ./
 
       - name: 🚀 Deploy
         uses: JamesIves/[email protected]
         with:
           branch: gh-pages
-          folder: ./website/build
+          folder: ./documentation/dist

.github/workflows/nodejs.yml

@@ -3,7 +3,7 @@
 
 name: Node.js CI
 
-on: 
+on:
   push:
     branches:
       - main
@@ -17,20 +17,20 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [18.x, 20.x]
 
     env:
       NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'pnpm'

.github/workflows/publish.yml

@@ -9,10 +9,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
 
       - name: Use Node.js 18.x
         uses: actions/setup-node@v4

.github/workflows/size-compare.yml

@@ -18,10 +18,10 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v2
 
-      - name: Use Node.js 18.x
-        uses: actions/setup-node@v3
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
         with:
-          node-version: 18.x
+          node-version: 20.x
           cache: 'pnpm'
 
       - name: Install dependencies

CONTRIBUTING.md

@@ -12,3 +12,26 @@
 > Note: be careful NOT to commit `babel-plugin-factories.json` with changed library name `@effector/patronum`
 
 When work is done, please remove `@effector/patronum` from integration packages via `pnpm remove @effector/patronum`, else CI can be broken.
+
+## Documentation
+
+All the documentation source code placed in `./documentation`. It is uses [astro](https://astro.build) and [starlight](https://starlight.astro.build) on top of it.
+
+Documentation for operators placed right in the operator directory:
+
+```
+./src/
+├── and/
+│   ├── and.fork.test.ts
+│   ├── and.test.ts
+│   ├── index.ts
+│   └── readme.md
+├── combine-events/
+│   ├── combine-events.fork.test.ts
+│   ├── combine-events.test.ts
+│   ├── index.ts
+│   └── readme.md
+...
+```
+
+Documentation uses [Content Layer API](https://docs.astro.build/en/reference/configuration-reference/#querying-and-rendering-with-the-content-layer-api). You may want to [read this discussion](https://github.com/withastro/starlight/discussions/2268).

README.md

@@ -1,6 +1,6 @@
 # <img src="logo.svg" title="effector patronum" alt="Effector Patronum logo" width="640px">
 
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) ![Node.js CI](https://github.com/effector/patronum/workflows/Node.js%20CI/badge.svg) [![Rate on Openbase](https://badges.openbase.com/js/rating/patronum.svg)](https://openbase.com/js/patronum?utm_source=embedded&utm_medium=badge&utm_campaign=rate-badge)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) ![Node.js CI](https://github.com/effector/patronum/workflows/Node.js%20CI/badge.svg)
 [![LICENSE](https://badgen.net/github/license/effector/patronum?color=green)](/LICENSE)
 [![Stars](https://badgen.net/github/stars/effector/patronum?color=green)](https://github.com/effector/patronum)
 [![Downloads](https://badgen.net/npm/dt/patronum)](https://npmjs.com/package/patronum)
@@ -16,7 +16,7 @@
 [codesandbox]: https://codesandbox.io/s/effector-patronum-playground-zuqjx
 [try-patronum-share]: https://share.effector.dev/Neewtbz3
 [jsdelivr]: https://www.jsdelivr.com/package/npm/patronum
-[unpkg]: https://unpkg.com/browse/patronum@1.7.0/
+[unpkg]: https://unpkg.com/browse/patronum@2/
 [npm]: https://www.npmjs.com/package/patronum
 [github]: https://github.com/effector/patronum
 [twitter-share]: https://twitter.com/intent/tweet?text=I%20used%20patronum!%0AGoing%20to%20Mars%20with%20%40effectorjs%20-%20data-flow%20powered%20tool%20to%20implement%20business%20logic.%0A%0Ahttps%3A%2F%2Fgithub.com%2Feffector%2Fpatronum%0A
@@ -44,13 +44,13 @@ const userLoadFx = createEffect();
 const $status = status({ effect: userLoadFx });
 ```
 
-You can read more at [documentation](https://patronum.effector.dev/docs/installation).
+You can read more at [documentation](https://patronum.effector.dev/guides/installation/).
 
 ## Migration guide
 
 Patronum had 3 breaking changes: 1) from `0.14` to `0.100`, 2) from `0.100` to `0.110`, 3) from `0.110` to `1.0`
 
-We have [migration guide](https://patronum.effector.dev/docs/migration-guide).
+We have [migration guide](https://patronum.effector.dev/guides/migration).
 
 # Development
 

documentation/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

documentation/.prettierrc.mjs

@@ -0,0 +1,17 @@
+/** @type {import("prettier").Config} */
+export default {
+  arrowParens: 'always',
+  printWidth: 120,
+  trailingComma: 'all',
+  singleQuote: true,
+  jsxSingleQuote: true,
+  plugins: ['prettier-plugin-astro'],
+  overrides: [
+    {
+      files: '*.astro',
+      options: {
+        parser: 'astro',
+      },
+    },
+  ],
+};

documentation/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

documentation/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

documentation/README.md

@@ -0,0 +1,55 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).

documentation/astro.config.mjs

@@ -0,0 +1,45 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://patronum.effector.dev',
+  integrations: [
+    starlight({
+      title: 'effector patronum ✨',
+      description: 'Operators library delivering modularity and convenience.',
+      logo: {
+        src: './src/assets/comet.png',
+      },
+      editLink: {
+        baseUrl: 'https://github.com/effector/patronum/edit/main/documentation',
+      },
+      social: {
+        github: 'https://github.com/effector/patronum',
+        telegram: 'https://t.me/effector_en',
+        'x.com': 'https://x.com/effectorjs',
+        reddit: 'https://www.reddit.com/r/effectorjs/',
+        discord: 'https://discord.gg/yHcMcuRWeC',
+        youtube: 'https://youtube.com/@effectorjs',
+      },
+      sidebar: [
+        {
+          label: 'Guides',
+          autogenerate: { directory: 'guides' },
+        },
+        {
+          label: 'Reference',
+          items: [
+            {
+              label: 'Operators',
+              link: '/operators',
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+  experimental: {
+    contentLayer: true,
+  },
+});

documentation/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "documentation",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "sync": "astro sync",
+    "preview": "astro preview",
+    "build": "astro check && astro build",
+    "astro": "astro",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "@astrojs/check": "^0.9.3",
+    "@astrojs/starlight": "^0.26.1",
+    "astro": "^4.15.1",
+    "sharp": "^0.32.5",
+    "starlight-package-managers": "^0.6.0",
+    "typescript": "^5.5.4"
+  },
+  "devDependencies": {
+    "prettier": "^3.3.3",
+    "prettier-plugin-astro": "^0.14.1"
+  }
+}

documentation/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://effector.patronum.dev/sitemap-index.xml

documentation/src/content/config.ts

@@ -0,0 +1,27 @@
+import { defineCollection, z } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+import { glob } from 'astro/loaders';
+
+const operators = defineCollection({
+  type: 'content_layer',
+  loader: glob({ pattern: '*/*.md', base: '../src' }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    slug: z.string(),
+    group: z.enum(['predicate', 'effect', 'timeouts', 'combination', 'debug']),
+    badge: z
+      .object({
+        variant: z
+          .enum(['note', 'danger', 'success', 'caution', 'tip', 'default'])
+          .default('default'),
+        text: z.string(),
+      })
+      .optional(),
+  }),
+});
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+  operators,
+};