commit 4d4d9a5d777443a60b4cfa850880b6d9ee59d724 Author: Lars Nolden Date: Fri Jul 31 12:14:54 2026 +0200 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..107304b --- /dev/null +++ b/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 `

${props.title}

`; + // 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!*