remult 0.25.8-exp.11 → 0.25.8-exp.13

package/README.md

@@ -1,7 +1,4 @@
 <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">
@@ -29,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
@@ -100,6 +74,9 @@ import { Entity, Fields } from 'remult'
   allowApiCrud: true,
 })
 export class Product {
+  @Fields.cuid()
+  id = ''
+
   @Fields.string()
   name = ''
 
@@ -108,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
@@ -178,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
@@ -228,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
@@ -256,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
@@ -273,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.
@@ -287,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).

package/esm/index.js

@@ -13,7 +13,7 @@ export { CustomSqlFilterBuilder, dbNamesOf, } from './src/filter/filter-consumer
 export { JsonDataProvider, } from './src/data-providers/json-data-provider.js'; //V
 export { JsonEntityOpfsStorage } from './src/data-providers/json-entity-opfs-storage.js';
 //export * from './src/data-api'; //reconsider if to make internal
-export { Controller, BackendMethod, ProgressListener, } from './src/server-action.js';
+export { Controller, BackendMethod, ProgressListener, ForbiddenError, } from './src/server-action.js';
 export { Allow, Remult, withRemult, isBackend, EventSource, } from './src/context.js';
 export { Sort } from './src/sort.js';
 export { CompoundIdField } from './src/CompoundIdField.js';

package/esm/migrations/update-migrations-ts-file.js

@@ -1,7 +1,7 @@
 // consider replacing with https://www.npmjs.com/package/ts-morph
-import ts from 'typescript';
-import * as fs from 'fs';
 export async function updateMigrationsFile(filePath, steps) {
+    const ts = await import('typescript');
+    const fs = await import('fs');
     let maxStep = -1;
     function buildSteps() {
         return steps.map((step) => ts.factory.createPropertyAssignment(ts.factory.createIdentifier((++maxStep).toString()), ts.factory.createIdentifier(step)));

package/esm/remult-better-sqlite3.js

@@ -38,8 +38,7 @@ export class BetterSqlite3SqlResult {
     result;
     constructor(result) {
         this.result = result;
-        this.rows =
-            result.map((row) => Object.keys(row).reduce((prev, curr) => ({ ...prev, [curr]: row[curr] }), {}));
+        this.rows = result;
     }
     rows;
     getColumnKeyInResultForIndexInSelect(index) {

package/esm/remult-bun-sqlite.js

@@ -0,0 +1,41 @@
+import { SqliteCoreDataProvider } from "./remult-sqlite-core.js";
+export class BunSqliteDataProvider extends SqliteCoreDataProvider {
+    constructor(db) {
+        super(() => new BunSqliteCommand(db), async () => { db.close(); });
+    }
+}
+class BunSqliteCommand {
+    db;
+    values = {};
+    i = 0;
+    constructor(db) {
+        this.db = db;
+    }
+    async execute(sql) {
+        const s = this.db.query(sql);
+        return new BunSqliteSqlResult(s.all(this.values));
+    }
+    addParameterAndReturnSqlToken(val) {
+        return this.param(val);
+    }
+    param(val) {
+        if (val instanceof Date)
+            val = val.valueOf();
+        if (typeof val === "boolean")
+            val = val ? 1 : 0;
+        const key = ':' + (this.i++);
+        this.values[key] = (val);
+        return key;
+    }
+}
+class BunSqliteSqlResult {
+    result;
+    constructor(result) {
+        this.result = result;
+        this.rows = result;
+    }
+    rows;
+    getColumnKeyInResultForIndexInSelect(index) {
+        return Object.keys(this.result[0])[index];
+    }
+}

package/esm/src/data-api.js

@@ -213,19 +213,29 @@ export class DataApi {
                 where.push(this.repository.metadata.options.apiPrefilter);
         }
         if (request) {
-            where.push(buildFilterFromRequestParameters(this.repository.metadata, {
+            let f = buildFilterFromRequestParameters(this.repository.metadata, {
                 get: (key) => {
-                    let result = request.get(key);
+                    let result = body?.where?.[key];
+                    if (result !== undefined)
+                        return result;
+                    result = request.get(key);
                     if (key.startsWith(customUrlToken) &&
                         result &&
                         typeof result === 'string')
                         return JSON.parse(result);
                     return result;
                 },
-            }));
+            });
+            if (this.repository.metadata.options.apiPreprocessFilter) {
+                f = await this.repository.metadata.options.apiPreprocessFilter(f, {
+                    metadata: this.repository.metadata,
+                    getFilterInfo: async (filter) => {
+                        return Filter.getInfo(this.repository.metadata, filter || f);
+                    },
+                });
+            }
+            where.push(f);
         }
-        if (body?.where)
-            where.push(Filter.entityFilterFromJson(this.repository.metadata, body.where));
         return { $and: where };
     }
     async doOnId(response, id, what) {
@@ -342,7 +352,7 @@ export class DataApi {
         }
         catch (err) {
             if (err.isForbiddenError)
-                response.forbidden();
+                response.forbidden(err.message);
             else
                 response.error(err, this.repository.metadata);
         }