first commit

README.md

@@ -0,0 +1,180 @@
+# borat-js 🇰🇿
+
+> Jagshemash! My name is borat-js. I am number four JavaScript framework in all of Kazakhstan. Very nice!
+
+**borat-js** is a gloriously ill-fitting frontend framework for building web apps that are *very nice*. It is like React, but with a moustache. It is like Vue, but the suit is grey and does not fit. Chenqui.
+
+## Why borat-js?
+
+Every year, 68 new JavaScript frameworks are released. **None of them** have ever been to Kazakhstan. This is a problem. borat-js solves this problem, and also many other problems that did not exist before borat-js.
+
+- ✅ **Virtual DOM?** No. We have *Potato DOM*. It is slower, but more honest.
+- ✅ **Zero dependencies.** We do not depend on anyone. Like proud Kazakh horse.
+- ✅ **TypeScript support.** TypeScript is support, yes, but we do not understand it.
+- ✅ **Server-side rendering.** The server is my neighbor's laptop. Please do not tell him.
+- ✅ **HMR (Hot Module Replacement).** The module is hot because it was in the sun. We replace it with a cold one. Great success!
+
+## Installation
+
+```bash
+npm install borat-js
+```
+
+If installation fails, it is not our fault. It is the fault of the npm registry, which is run by people who have never tasted fermented horse milk.
+
+## Quick Start
+
+Create your first borat-js app:
+
+```js
+import { Borat, veryNice, greatSuccess } from 'borat-js';
+
+const app = new Borat('#root');
+
+app.render(veryNice('h1', {}, 'Hello, I am web page!'));
+```
+
+Run it:
+
+```bash
+npx borat dev
+```
+
+Output:
+
+```
+Jagshemash! Dev server starting...
+Server is running on port 3000.
+Great success!
+```
+
+## Core Concepts
+
+### Components
+
+In borat-js, a component is a function that returns markup. If it does not return markup, we pretend it did.
+
+```js
+import { component } from 'borat-js';
+
+const MyComponent = component((props) => {
+  return `<h1>${props.title}</h1>`;
+  // If title is undefined, we render "Very nice!" instead.
+  // This is not a bug. This is a feature. Very nice feature.
+});
+```
+
+### State Management
+
+borat-js uses **KazakhStore**, the finest state management library east of Uzbekistan.
+
+```js
+import { createStore } from 'borat-js/store';
+
+const store = createStore({
+  cheese: 5,
+  suit: 'grey (ill-fitting)',
+});
+
+store.set('cheese', 10); // Very nice!
+store.get('cheese');     // 10. Great success!
+```
+
+State is immutable, because we do not know how to mutate it.
+
+### The `!not` Operator
+
+Other frameworks have `!` for negation. borat-js has `not!`, which works like a Borat joke:
+
+```js
+const isFast = false;
+
+console.log(isFast); // false
+console.log(isFast, '...not!'); // true
+```
+
+> ⚠️ Warning: The `not!` operator only works 5 minutes after the initial statement. This is by design.
+
+### Conditional Rendering
+
+```js
+app.render(
+  veryNice('div', {}, [
+    condition(user.isLoggedIn, [
+      veryNice('p', {}, `Welcome, ${user.name}!`),
+    ], [
+      veryNice('p', {}, 'You will never get this! You will never get this!'),
+    ]),
+  ])
+);
+```
+
+### Effects
+
+```js
+import { effect } from 'borat-js';
+
+effect(() => {
+  document.title = `Cheese: ${store.get('cheese')}`;
+});
+// Runs every time cheese changes.
+// Cheese changes often. This is Kazakhstan.
+```
+
+## API Reference
+
+| Function | Description |
+|---|---|
+| `veryNice(tag, props, children)` | Creates a vnode. If anything goes wrong, still very nice. |
+| `greatSuccess()` | Returns `true`. Always. Great success! |
+| `wahWahWeeWah(promise)` | Awaits a promise with a loading spinner shaped like a moustache. |
+| `chenqui(callback)` | Registers a callback to run when the component is unmounted. "Thank you" for your service. |
+| `not(boolean)` | See above. Use responsibly. |
+| `myWife(state)` | Deep-freezes state. Nobody touches it. *My wife!* |
+| `kingInTheCastle(component)` | Marks a component as protected. Only the king may re-render it. |
+
+## Performance
+
+We benchmarked borat-js against other frameworks:
+
+| Framework | Speed | Moustache |
+|---|---|---|
+| React | Fast | No |
+| Vue | Fast | No |
+| Svelte | Very fast | No |
+| **borat-js** | *Adequate* | **YES** |
+
+As you can see, borat-js wins in the only category that matters.
+
+## FAQ
+
+**Q: Is borat-js production ready?**
+A: Yes! It has been in production at the Kazakhstan Ministry of Information since 2006. Uptime: 3 days. Not consecutive.
+
+**Q: How do I handle errors?**
+A: Errors are a Western concept. In borat-js, nothing is an error. Everything is either *very nice* or *a great success*.
+
+**Q: Does it support SSR?**
+A: Yes, see above. My neighbor's laptop. He does not know. Please do not tell.
+
+**Q: What about accessibility?**
+A: borat-js is accessible to everyone, except my neighbor Nursultan Tulyakbay. He knows what he did.
+
+**Q: Can I contribute?**
+A: Yes! Bring cheese.
+
+## Contributing
+
+1. Fork the repo.
+2. Make a change.
+3. Say "Great success!" out loud.
+4. Open a pull request.
+5. If CI fails, say "...not!" and try again.
+
+## License
+
+MIT. (Ministry of Information Technology, Kazakhstan.)
+
+---
+
+*borat-js is a parody project. It is not affiliated with, endorsed by, or authorized by Sacha Baron Cohen, his estate, his lawyers, or the glorious nation of Kazakhstan. Any resemblance to a real, performant JavaScript framework is purely coincidental. Very nice!*