remult 0.25.8-exp.9 → 0.26.0-exp.17

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/graphql.js

@@ -118,6 +118,11 @@ export function remultGraphql(options) {
     for (const meta of entities) {
         const orderByFields = [];
         const key = meta.key;
+        const requiredWhereArg = {
+            key: 'where',
+            value: `${key}Where!`,
+            comment: `Remult filtering options`,
+        };
         const currentType = upsertTypes(getMetaType(meta), 'type_impl_node');
         if (key) {
             const createResultPromise = (work) => {
@@ -213,6 +218,7 @@ export function remultGraphql(options) {
                 });
             };
             const queryArgsConnection = getQueryArgsConnection(key);
+            let pluralEntityKey = key;
             let getSingleEntityKey = toCamelCase(getMetaType(meta));
             if (getSingleEntityKey === toCamelCase(key))
                 getSingleEntityKey = 'single' + key;
@@ -325,66 +331,126 @@ export function remultGraphql(options) {
             if (checkCanExist(meta.options.allowApiUpdate)) {
                 // update
                 const updateInput = `Update${getMetaType(meta)}Input`;
-                const updatePayload = `Update${getMetaType(meta)}Payload`;
-                const updateResolverKey = `update${getMetaType(meta)}`;
-                root_mutation.fields.push({
-                    key: updateResolverKey,
-                    args: [
-                        argId,
-                        { key: 'patch', value: `${updateInput}!` },
-                        argClientMutationId,
-                    ],
-                    value: `${updatePayload}`,
-                    comment: `Update a \`${getMetaType(meta)}\``,
-                });
-                currentType.mutation.update.input = upsertTypes(updateInput, 'input');
-                currentType.mutation.update.payload = upsertTypes(updatePayload);
-                currentType.mutation.update.payload.fields.push({
-                    key: `${toCamelCase(getMetaType(meta))}`,
-                    value: `${getMetaType(meta)}`,
-                }, argErrorDetail, argClientMutationId);
-                root[updateResolverKey] = handleMutationWithErrors(async (dApi, response, setResult, arg1, req) => {
-                    await dApi.put({
-                        ...response,
-                        success: (y) => {
-                            const orig = { ...y };
-                            currentType.query.resultProcessors.forEach((z) => z(y, orig));
-                            setResult({
-                                [toCamelCase(getMetaType(meta))]: y,
-                            });
-                        },
-                    }, arg1.id, arg1.patch);
-                });
-                resolversMutation[updateResolverKey] = (origItem, args, req, gqlInfo) => root[updateResolverKey](args, req, gqlInfo);
+                {
+                    const updatePayload = `Update${getMetaType(meta)}Payload`;
+                    const updateResolverKey = `update${getMetaType(meta)}`;
+                    root_mutation.fields.push({
+                        key: updateResolverKey,
+                        args: [
+                            argId,
+                            { key: 'patch', value: `${updateInput}!` },
+                            argClientMutationId,
+                        ],
+                        value: `${updatePayload}`,
+                        comment: `Update a \`${getMetaType(meta)}\``,
+                    });
+                    currentType.mutation.update.input = upsertTypes(updateInput, 'input');
+                    currentType.mutation.update.payload = upsertTypes(updatePayload);
+                    currentType.mutation.update.payload.fields.push({
+                        key: `${toCamelCase(getMetaType(meta))}`,
+                        value: `${getMetaType(meta)}`,
+                    }, argErrorDetail, argClientMutationId);
+                    resolversMutation[updateResolverKey] = (origItem, args, req, gqlInfo) => handleMutationWithErrors(async (dApi, response, setResult, arg1, req) => {
+                        await dApi.put({
+                            ...response,
+                            success: (y) => {
+                                const orig = { ...y };
+                                currentType.query.resultProcessors.forEach((z) => z(y, orig));
+                                setResult({
+                                    [toCamelCase(getMetaType(meta))]: y,
+                                });
+                            },
+                        }, arg1.id, arg1.patch);
+                    })(args, req);
+                }
+                // update many
+                {
+                    const updateManyPayload = `UpdateMany${upperFirstChar(pluralEntityKey)}Payload`;
+                    const updateManyResolverKey = `updateMany${upperFirstChar(pluralEntityKey)}`;
+                    root_mutation.fields.push({
+                        key: updateManyResolverKey,
+                        args: [
+                            requiredWhereArg,
+                            { key: 'patch', value: `${updateInput}!` },
+                            argClientMutationId,
+                        ],
+                        value: `${updateManyPayload}`,
+                        comment: `Update many \`${pluralEntityKey}\``,
+                    });
+                    currentType.mutation.update.payload = upsertTypes(updateManyPayload);
+                    currentType.mutation.update.payload.fields.push({
+                        key: `updated`,
+                        value: `Int!`,
+                    }, argErrorDetail, argClientMutationId);
+                    resolversMutation[updateManyResolverKey] = (origItem, args, req, gqlInfo) => handleMutationWithErrors(async (dApi, response, setResult, arg1, req) => {
+                        await dApi.updateManyImplementation({
+                            ...response,
+                            success: (updateManyResult) => {
+                                setResult(updateManyResult);
+                            },
+                        }, { get: () => undefined }, {
+                            ...translateWhereToRestBody(meta.fields, arg1),
+                            set: arg1.patch,
+                        });
+                    })(args, req);
+                }
             }
             if (checkCanExist(meta.options.allowApiDelete)) {
                 // delete
-                const deletePayload = `Delete${getMetaType(meta)}Payload`;
-                const deleteResolverKey = `delete${getMetaType(meta)}`;
-                root_mutation.fields.push({
-                    key: deleteResolverKey,
-                    args: [argId, argClientMutationId],
-                    value: `${deletePayload}`,
-                    comment: `Delete a \`${getMetaType(meta)}\``,
-                });
-                currentType.mutation.delete.payload = upsertTypes(deletePayload);
-                const deletedResultKey = `id`;
-                const type = meta.idMetadata.field instanceof CompoundIdField
-                    ? 'String'
-                    : getGraphqlBaseType(meta.idMetadata.field);
-                currentType.mutation.delete.payload.fields.push({
-                    key: deletedResultKey,
-                    value: `${type}`,
-                }, argErrorDetail, argClientMutationId);
-                root[deleteResolverKey] = handleMutationWithErrors(async (dApi, response, setResult, arg1, req) => {
-                    await dApi.delete({
-                        ...response,
-                        deleted: () => {
-                            setResult({ [deletedResultKey]: arg1.id });
-                        },
-                    }, arg1.id);
-                });
-                resolversMutation[deleteResolverKey] = (origItem, args, req, gqlInfo) => root[deleteResolverKey](args, req, gqlInfo);
+                {
+                    const deletePayload = `Delete${getMetaType(meta)}Payload`;
+                    const deleteResolverKey = `delete${getMetaType(meta)}`;
+                    root_mutation.fields.push({
+                        key: deleteResolverKey,
+                        args: [argId, argClientMutationId],
+                        value: `${deletePayload}`,
+                        comment: `Delete a \`${getMetaType(meta)}\``,
+                    });
+                    currentType.mutation.delete.payload = upsertTypes(deletePayload);
+                    const deletedResultKey = `id`;
+                    const type = meta.idMetadata.field instanceof CompoundIdField
+                        ? 'String'
+                        : getGraphqlBaseType(meta.idMetadata.field);
+                    currentType.mutation.delete.payload.fields.push({
+                        key: deletedResultKey,
+                        value: `${type}`,
+                    }, argErrorDetail, argClientMutationId);
+                    resolversMutation[deleteResolverKey] = (origItem, args, req) => handleMutationWithErrors(async (dApi, response, setResult, arg1, req) => {
+                        await dApi.delete({
+                            ...response,
+                            deleted: () => {
+                                setResult({ [deletedResultKey]: arg1.id });
+                            },
+                        }, arg1.id);
+                    })(args, req);
+                }
+                // delete
+                {
+                    const deleteManyPayload = `DeleteMany${upperFirstChar(pluralEntityKey)}Payload`;
+                    const deleteManyResolverKey = `deleteMany${upperFirstChar(pluralEntityKey)}`;
+                    root_mutation.fields.push({
+                        key: deleteManyResolverKey,
+                        args: [requiredWhereArg, argClientMutationId],
+                        value: `${deleteManyPayload}`,
+                        comment: `Delete many \`${pluralEntityKey}\``,
+                    });
+                    currentType.mutation.delete.payload = upsertTypes(deleteManyPayload);
+                    const type = meta.idMetadata.field instanceof CompoundIdField
+                        ? 'String'
+                        : getGraphqlBaseType(meta.idMetadata.field);
+                    currentType.mutation.delete.payload.fields.push({
+                        key: 'deleted',
+                        value: `Int!`,
+                    }, argErrorDetail, argClientMutationId);
+                    resolversMutation[deleteManyResolverKey] = (origItem, args, req) => handleMutationWithErrors(async (dApi, response, setResult, arg1, req) => {
+                        await dApi.deleteMany({
+                            ...response,
+                            success: (deleteManyResult) => {
+                                setResult(deleteManyResult);
+                            },
+                        }, { get: () => undefined }, translateWhereToRestBody(meta.fields, arg1));
+                    })(args, req);
+                }
             }
             const whereTypeFields = [];
             for (const f of meta.fields) {
@@ -838,6 +904,12 @@ function getGraphqlBaseType(field) {
 function getMetaType(entityMeta) {
     return entityMeta.entityType.name;
 }
+function upperFirstChar(str) {
+    return str
+        .split('')
+        .map((c, i) => (i === 0 ? c.toUpperCase() : c))
+        .join('');
+}
 function toCamelCase(str) {
     return str
         .split('')

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';