181 lines
5.1 KiB
Markdown
181 lines
5.1 KiB
Markdown
# 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!*
|