remult 0.25.8 → 0.26.0

package/README.md

@@ -1,27 +1,18 @@
 <div align="center">
-  <a href="http://remult.dev/">
-    <img src="https://github.com/remult/remult/raw/master/docs/public/logo.png" width="140" height="140">
-  </a>
   <h1>Remult</h1>
   <p>Full-stack CRUD, simplified, with SSOT TypeScript entities</p>
 	<a href="https://circleci.com/gh/remult/remult/tree/master" rel="nofollow">
-		<img alt="CircleCI" src="https://circleci.com/gh/remult/remult/tree/master.svg?style=shield">
-	</a>
+		<img alt="CircleCI" src="https://circleci.com/gh/remult/remult/tree/master.svg?style=shield"></a>
 	<a href="https://codecov.io/gh/remult/remult" rel="nofollow">
-        	<img src="https://codecov.io/gh/remult/remult/branch/master/graph/badge.svg?token=LYWQRUN3D1"/>
-      	</a>
+        	<img src="https://codecov.io/gh/remult/remult/branch/master/graph/badge.svg?token=LYWQRUN3D1"/></a>
     	<a href="https://raw.githubusercontent.com/remult/remult/master/LICENSE" rel="nofollow">
-		<img alt="GitHub license" src="https://img.shields.io/badge/license-MIT-blue.svg">
-	</a>
+		<img alt="GitHub license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
 	<a href="https://www.npmjs.com/package/remult" rel="nofollow">
-		<img alt="npm version" src="https://badge.fury.io/js/remult.svg">
-	</a>
+		<img alt="npm version" src="https://badge.fury.io/js/remult.svg"></a>
 	<a href="https://www.npmjs.com/package/remult" rel="nofollow">
-		<img alt="npm downloads" src="https://img.shields.io/npm/dm/remult">
-	</a>
+		<img alt="npm downloads" src="https://img.shields.io/npm/dm/remult"></a>
 	<a href="https://discord.gg/GXHk7ZfuG5" rel="nofollow">
-		<img alt="Join Discord" src="https://badgen.net/discord/online-members/GXHk7ZfuG5?icon=discord&label=Discord"/>
-	</a>
+		<img alt="Join Discord" src="https://badgen.net/discord/members/GXHk7ZfuG5?icon=discord&label=Discord"/></a>
 </div>
 
 <br/>
@@ -35,67 +26,44 @@
 <hr/>
 <br/>
 
-<a href="https://www.youtube.com/watch?v=rEoScmSVNUE" target="_blank">
-  <p align="center">
-    <img src="https://github.com/remult/remult/raw/master/static/images/video-thumbnail.jpg" alt="Video thumbnail"  />
-  </p>
-</a>
-
-<a href="https://www.youtube.com/watch?v=rEoScmSVNUE" target="_blank">
-  <p align="center">Watch code demo on YouTube here (14 mins)</p>
-</a>
-
 ## What is Remult?
 
-**Remult** is a full-stack CRUD framework that uses your **TypeScript entities
-as a single source of truth for your API, frontend type-safe API client and
-backend ORM**.
+Remult uses **TypeScript entities** as a single source of truth for: ✅ CRUD + Realtime API, ✅ frontend type-safe API client, and
+✅ backend ORM.
 
-- :zap: Zero-boilerplate CRUD API routes with paging, sorting, and filtering for Express / Fastify / Next.js / NestJS / Koa / others...
-- :ok_hand: Fullstack type-safety for API queries, mutations and RPC, without code generation
-- :sparkles: Input validation, defined once, runs both on the backend and on the frontend for best UX
-- :lock: Fine-grained code-based API authorization
+- :zap: **Zero-boilerplate CRUD + Realtime API** with paging, sorting, and filtering
+- :ok_hand: **Fullstack type-safety** for API queries, mutations and RPC, without code generation
+- :sparkles: Input validation, **defined once**, runs both on the backend and on the frontend for best UX
+- :lock: Fine-grained **code-based API authorization**
 - :relieved: Incrementally adoptable
-- :rocket: Production ready
-- :mega: **NEW - Zero-boilerplate realtime live-queries**
-
-### Status
 
-Remult is **production-ready** and, in fact, used in production apps since 2018.
-However, we’re keeping the major version at zero so we can use community
-feedback to finalize the v1 API.
+**Remult supports all major databases**, including: PostgreSQL, MySQL, SQLite, MongoDB, MSSQL and Oracle.
 
-## Motivation
-
-Full-stack web development is (still) too complicated. **Simple CRUD, a common
-requirement of any business application, should be simple to build, maintain,
-and extend** when the need arises.
-
-Remult abstracts away repetitive, boilerplate, error-prone, and poorly designed
-code on the one hand, and enables total flexibility and control on the other.
-**Remult helps building fullstack apps using only TypeScript code you can easily
-follow and safely refactor**, and fits nicely into any existing or new project
-by being minimalistic and completely unopinionated regarding the developer’s
-choice of other frameworks and tools.
-
-Other frameworks tend to fall into either too much abstraction (no-code,
-low-code, BaaS) or partial abstraction (MVC frameworks, GraphQL, ORMs, API
-generators, code generators), and tend to be opinionated regarding the
-development tool-chain, deployment environment, configuration/conventions or
-DSL. Remult attempts to strike a better balance.
+**Remult is frontend and backend framework agnostic** and comes with adapters for Express, Fastify, Next.js, Nuxt, SvelteKit, Nest, Koa, Hapi and Hono.
 
-## Installation
+Remult promotes a **consistent query syntax for both frontend and Backend code**:
 
-The _remult_ package is one and the same for both the frontend bundle and the
-backend. Install it once for a monolith project or per-repo in a monorepo.
+```ts
+// Frontend - GET: /api/products?_limit=10&unitPrice.gt=5,_sort=name
+// Backend  - 'select name, unitPrice from products where unitPrice > 5 order by name limit 10'
+await repo(Product).find({
+  limit: 10,
+  orderBy: {
+    name: 'asc',
+  },
+  where: {
+    unitPrice: { $gt: 5 },
+  },
+})
 
-```sh
-npm i remult
+// Frontend - PUT: '/api/products/product7' (body: { "unitPrice" : 7 })
+// Backend  - 'update products set unitPrice = 7 where id = product7'
+await repo(Product).update('product7', { unitPrice: 7 })
 ```
 
 ## Usage
 
-### Define model classes
+### Define schema in code
 
 ```ts
 // shared/product.ts
@@ -106,6 +74,9 @@ import { Entity, Fields } from 'remult'
   allowApiCrud: true,
 })
 export class Product {
+  @Fields.cuid()
+  id = ''
+
   @Fields.string()
   name = ''
 
@@ -114,65 +85,72 @@ export class Product {
 }
 ```
 
-### Setup API backend using an Express middleware
+### Add backend API with a [single line of code](https://remult.dev/docs/quickstart#server-side-initialization)
+
+_Example:_
 
 ```ts
 // backend/index.ts
 
 import express from 'express'
-import { remultExpress } from 'remult/remult-express'
+import { remultExpress } from 'remult/remult-express' // adapters for: Fastify, Next.js, Nuxt, SvelteKit, Nest, more...
+import { createPostgresDataProvider } from "remult/postgres" // supported: PostgreSQL, MySQL, SQLite, MongoDB, MSSQL and Oracle
 import { Product } from '../shared/product'
 
-const port = 3001
 const app = express()
 
 app.use(
   remultExpress({
     entities: [Product],
+    dataProvider: createPostgresDataProvider({
+      connectionString: 'postgres://user:password@host:5432/database"',
+    }),
   }),
 )
 
-app.listen(port, () => {
-  console.log(`Example API listening at http://localhost:${port}`)
-})
+app.listen()
 ```
 
-### :rocket: API Ready
-
-```sh
-> curl http://localhost:3001/api/products
-
-[{"name":"Tofu","unitPrice":5}]
-```
+Remult adds route handlers for a fully functional REST API and realtime live-query endpoints, optionally including an [Open API](https://remult.dev/docs/adding-swagger) spec and a [GraphQL](https://remult.dev/docs/adding-graphql) endpoint
 
-### Find and manipulate data in type-safe frontend code
+### Fetch data with type-safe frontend code
 
 ```ts
-// frontend/code.ts
-
-import { remult } from 'remult'
-import { Product } from '../shared/product'
-
-async function increasePriceOfTofu(priceIncrease: number) {
-  const productsRepo = remult.repo(Product)
-
-  const product = await productsRepo.findFirst({ name: 'Tofu' }) // filter is passed through API request all the way to the db
-  product.unitPrice += priceIncrease
-  productsRepo.save(product) // mutation request updates the db with no boilerplate code
-}
+const [products, setProducts] = useState<Product[]>([])
+
+useEffect(() => {
+  repo(Product)
+    .find({
+      limit: 10,
+      orderBy: {
+        name: 'asc',
+      },
+      where: {
+        unitPrice: { $gt: 5 },
+      },
+    })
+    .then(setProducts)
+}, [])
 ```
 
-### ..._exactly_ the same way as in backend code
+### :mega: Realtime Live Queries
 
 ```ts
-@BackendMethod({ allowed: Allow.authenticated })
-static async increasePriceOfTofu(priceIncrease: number) {
-  const productsRepo = remult.repo(Product);
-
-  const product = await productsRepo.findFirst({ name: 'Tofu' }); // use Remult in the backend as an ORM
-  product.unitPrice += priceIncrease;
-  productsRepo.save(product);
-}
+useEffect(() => {
+  return repo(Product)
+    .liveQuery({
+      limit: 10,
+      orderBy: {
+        name: 'asc',
+      },
+      where: {
+        unitPrice: { $gt: 5 },
+      },
+    })
+    .subscribe((info) => {
+      setProducts(info.applyChanges)
+    })
+}, [])
 ```
 
 ### :ballot_box_with_check: Data validation and constraints - defined once
@@ -184,49 +162,52 @@ import { Entity, Fields, Validators } from 'remult'
   allowApiCrud: true,
 })
 export class Product {
+  @Fields.cuid()
+  id = ''
+
   @Fields.string({
     validate: Validators.required,
   })
   name = ''
 
-  @Fields.string<Product>({
-    validate: (product) => {
-      if (product.description.trim().length < 50) {
-        throw 'too short'
-      }
-    },
-  })
-  description = ''
-
-  @Fields.number({
-    validate: (_, field) => {
-      if (field.value < 0) {
-        field.error = 'must not be less than 0' // or: throw "must not be less than 0";
-      }
-    },
+  @Fields.number<Product>({
+    validate: (product) => product.unitPrice > 0 || 'must be greater than 0',
   })
   unitPrice = 0
 }
 ```
 
-### Enforced in frontend:
+#### Enforced in frontend:
 
 ```ts
-const product = productsRepo.create()
-
 try {
-  await productsRepo.save(product)
+  await repo(Product).insert({ name: '', unitPrice: -1 })
 } catch (e: any) {
-  console.error(e.message) // Browser console will display - "Name: required"
+  console.error(e)
+/* Detailed error object ->
+{
+  "modelState": {
+    "name": "Should not be empty",
+    "unitPrice": "must be greater than 0"
+  },
+  "message": "Name: Should not be empty"
+}
+*/
 }
 ```
 
-### Enforced in backend:
+#### Enforced in backend:
 
-```sh
-> curl http://localhost:3001/api/products -H "Content-Type: application/json" -d "{""unitPrice"":-1}"
-
-{"modelState":{"unitPrice":"must not be less than 0","name":"required"},"message":"Name: required"}
+```ts
+// POST '/api/products' BODY: { "name":"", "unitPrice":-1 }
+// Response: status 400, body:
+{
+  "modelState": {
+    "name": "Should not be empty",
+    "unitPrice": "must be greater than 0"
+  },
+  "message": "Name: Should not be empty"
+}
 ```
 
 ### :lock: Secure the API with fine-grained authorization
@@ -234,21 +215,60 @@ try {
 ```ts
 @Entity<Article>('Articles', {
   allowApiRead: true,
-  allowApiInsert: (_, remult) => remult.authenticated(),
-  allowApiUpdate: (article, remult) => article.author.id == remult.user.id,
+  allowApiInsert: Allow.authenticated,
+  allowApiUpdate: (article) => article.author == remult.user.id,
+  apiPrefilter: () => {
+    if (remult.isAllowed('admin')) return {}
+    return {
+      author: remult.user.id,
+    }
+  },
 })
 export class Article {
   @Fields.string({ allowApiUpdate: false })
   slug = ''
 
-  @Field(() => Profile, { allowApiUpdate: false })
-  author!: Profile
+  @Fields.string({ allowApiUpdate: false })
+  authorId = remult.user!.id
 
   @Fields.string()
   content = ''
 }
 ```
 
+### :rocket: Relations
+
+```ts
+await repo(Categories).find({
+  orderBy: {
+    name: 'asc ',
+  },
+  include: {
+    products: {
+      where: {
+        unitPrice: { $gt: 5 },
+      },
+    },
+  },
+})
+
+// Entity Definitions
+export class Product {
+  //...
+  @Relations.toOne(Category)
+  category?: Category
+}
+export class Category {
+  //...
+  @Relations.toMany<Category, Product>(() => Product, `category`)
+  products?: Product[]
+}
+```
+
+### Automatic admin UI
+
+![Automatic admin UI](static/images/admin-ui.gif)
+
 ## What about complex CRUD?
 
 While simple CRUD shouldn’t require any backend coding, using Remult means
@@ -262,12 +282,20 @@ numerous ways:
   [entity lifecycle hooks](https://remult.dev/docs/ref_entity.html#saving)
   (before/after saving/deleting)
 - Backend only updatable fields (e.g. “last updated at”)
-- Many-to-one [relations](https://remult.dev/docs/entity-relations.html) with
-  [lazy/eager loading](https://remult.dev/docs/lazy-loading-of-related-entities.html)
+- [Relations](https://remult.dev/docs/entity-relations.html)
 - Roll-your-own type-safe endpoints with
   [Backend Methods](https://remult.dev/docs/backendMethods.html)
 - Roll-your-own low-level endpoints (Express, Fastify, koa, others…)
 
+## Installation
+
+The _remult_ package is one and the same for both the frontend bundle and the
+backend. Install it once for a monolith project or per-repo in a monorepo.
+
+```sh
+npm i remult
+```
+
 ## Tutorials
 
 The best way to learn Remult is by following a tutorial of a simple Todo web app
@@ -279,6 +307,18 @@ with a Node.js Express backend.
 - [Tutorial with Next.js](https://remult.dev/tutorials/react-next/)
 - [Tutorial with Sveltekit](https://remult.dev/tutorials/sveltekit/)
 
+## Demo
+
+<a href="https://www.youtube.com/watch?v=rEoScmSVNUE" target="_blank">
+  <p align="center">
+    <img src="https://github.com/remult/remult/raw/master/static/images/video-thumbnail.jpg" alt="Video thumbnail"  />
+  </p>
+</a>
+
+<a href="https://www.youtube.com/watch?v=rEoScmSVNUE" target="_blank">
+  <p align="center">Watch code demo on YouTube here (14 mins)</p>
+</a>
+
 ## Documentation
 
 The [documentation](https://remult.dev/docs) covers the main features of Remult.
@@ -293,6 +333,31 @@ However, it is still a work-in-progress.
 - [CRM demo](https://github.com/remult/crm-demo) with a React +
   [MUI](https://mui.com) front-end and Postgres database.
 
+### Status
+
+Remult is **production-ready** and, in fact, used in production apps since 2018.
+However, we’re keeping the major version at zero so we can use community
+feedback to finalize the v1 API.
+
+## Motivation
+
+Full-stack web development is (still) too complicated. **Simple CRUD, a common
+requirement of any business application, should be simple to build, maintain,
+and extend** when the need arises.
+
+Remult abstracts away repetitive, boilerplate, error-prone, and poorly designed
+code on the one hand, and enables total flexibility and control on the other.
+**Remult helps building fullstack apps using only TypeScript code you can easily
+follow and safely refactor**, and fits nicely into any existing or new project
+by being minimalistic and completely unopinionated regarding the developer’s
+choice of other frameworks and tools.
+
+Other frameworks tend to fall into either too much abstraction (no-code,
+low-code, BaaS) or partial abstraction (MVC frameworks, GraphQL, ORMs, API
+generators, code generators), and tend to be opinionated regarding the
+development tool-chain, deployment environment, configuration/conventions or
+DSL. Remult attempts to strike a better balance.
+
 ## Contributing
 
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).