Merge branch 'next' into custom-actions

Author: SerVitasik

adminforth/commands/createApp/templates/index.ts.hbs

@@ -77,7 +77,6 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   });
 
   admin.express.listen(port, () => {
-    console.log(`Example app listening at http://localhost:${port}`);
     console.log(`\n⚡ AdminForth is available at http://localhost:${port}${ADMIN_BASE_URL}\n`);
   });
 }

adminforth/dataConnectors/clickhouse.ts

@@ -7,8 +7,8 @@ import { AdminForthDataTypes, AdminForthFilterOperators, AdminForthSortDirection
 
 class ClickhouseConnector extends AdminForthBaseConnector implements IAdminForthDataSourceConnector {
 
-    dbName: string;
-    url: string;
+  dbName: string;
+  url: string;
 
   async setupClient(url): Promise<void> {
     this.dbName = new URL(url).pathname.replace('/', '');
@@ -217,7 +217,13 @@ class ClickhouseConnector extends AdminForthBaseConnector implements IAdminForth
         sort: { field: string, direction: AdminForthSortDirections }[], 
         filters: { field: string, operator: AdminForthFilterOperators, value: any }[],
     }): Promise<any[]> {
-      const columns = resource.dataSourceColumns.map((col) => col.name).join(', ');
+      const columns = resource.dataSourceColumns.map((col) => {
+        // for decimal cast to string
+        if (col.type == AdminForthDataTypes.DECIMAL) {
+          return `toString(${col.name}) as ${col.name}`
+        }
+        return col.name;
+      }).join(', ');
       const tableName = resource.table;
 
       const where = this.whereClause(resource, filters);

adminforth/dataConnectors/mysql.ts

@@ -8,7 +8,12 @@ class MysqlConnector extends AdminForthBaseConnector implements IAdminForthDataS
 
   async setupClient(url): Promise<void> {
     try {
-      this.client = await mysql.createConnection(url);
+      this.client = mysql.createPool({
+        uri: url,
+        waitForConnections: true,
+        connectionLimit: 10,  // Adjust based on your needs
+        queueLimit: 0
+      });
     } catch (e) {
       console.error(`Failed to connect to MySQL: ${e}`);
     }
@@ -33,7 +38,7 @@ class MysqlConnector extends AdminForthBaseConnector implements IAdminForthDataS
   };
 
   async discoverFields(resource) {
-    const [results] = await this.client.query("SHOW COLUMNS FROM " + resource.table);
+    const [results] = await this.client.execute("SHOW COLUMNS FROM " + resource.table);
     const fieldTypes = {};
     results.forEach((row) => {
       const field: any = {};
@@ -231,7 +236,7 @@ class MysqlConnector extends AdminForthBaseConnector implements IAdminForthDataS
     if (process.env.HEAVY_DEBUG_QUERY) {
       console.log('🪲📜 MySQL Q:', q, 'values:', filterValues);
     }
-    const [results] = await this.client.query(q, filterValues);
+    const [results] = await this.client.execute(q, filterValues);
     return +results[0]["COUNT(*)"];
   }
 
@@ -243,7 +248,7 @@ class MysqlConnector extends AdminForthBaseConnector implements IAdminForthDataS
       if (process.env.HEAVY_DEBUG_QUERY) {
         console.log('🪲📜 MySQL Q:', q);
       }
-      const [results] = await this.client.query(q);
+      const [results] = await this.client.execute(q);
       const { min, max } = results[0];
       result[col.name] = {
         min, max,

adminforth/documentation/docs/tutorial/03-Customization/05-limitingAccess.md

@@ -9,7 +9,7 @@ Before we start it is worth to mention that callbacks or scalars defined in `all
 
 As you can see allowedAction callbacks are called in parallel in async manner. However it is important to keep them fast and not to make any slow operations in them, to keep UI responsive.
 
-## Statically disable some action
+## Statically disable some action on resource
 
 You can use `options.allowedActions` on resource to limit access to the resource actions (list, show, create, edit, delete).
 
@@ -33,7 +33,43 @@ If you want to disable deletion of the resource records for all users:
 }
 ```
 
-## Disable some action based on logged in user record or role
+## Disable full access to resource based on logged in user record or role
+
+If you want to disable all actions to the resource for all users except users with role `superadmin`:
+
+```ts title="./resources/adminuser.ts"
+{
+  ...
+  resourceId: 'adminuser',
+  ...
+//diff-add
+  options: {
+//diff-add
+    allowedActions: {
+//diff-add
+      all: async ({ adminUser }: { adminUser: AdminUser }): Promise<boolean> => {
+//diff-add
+        return adminUser.dbUser.role === 'superadmin';
+//diff-add
+      }
+//diff-add
+    }
+//diff-add
+  }
+}
+```
+
+> ☝️ This will not hide link to the resource in the menu, you should separately use [menuItem.visible](/docs/tutorial/Customization/menuConfiguration/#visibility-of-menu-items) to hide it.
+
+
+
+> ☝️ instead of reading role from user you can check permission using complex ACL/RBAC models with permissions stored in the database.
+> However we recommend you to keep in mind that allowedActions callback is called on every request related to resource, so it should be fast.
+> So try to minimize requests to database as much as possible.
+
+
+
+## Disable only some action based on logged in user record or role
 
 If you want to disable deletion of apartments for all users apart from users with role `superadmin`:
 
@@ -61,11 +97,7 @@ import type { AdminUser } from  'adminforth';
 }
 ```
 
-> ☝️ instead of reading role from user you can check permission using complex ACL/RBAC models with permissions stored in the database.
-> However we recommend you to keep in mind that allowedActions callback is called on every request related to resource, so it should be fast.
-> So try to minimize requests to database as much as possible.
-
-## Reuse the same callback for multiple actions
+### Reuse the same callback for multiple actions
 
 Let's disable creating and editing of new users for all users apart from users with role `superadmin`, and at the same time disable deletion for all users:
 
@@ -80,6 +112,8 @@ async function canModifyUsers({ adminUser }: { adminUser: AdminUser }): Promise<
 //diff-add
 }
 
+...
+
 {
   ...
   resourceId: 'adminuser',
@@ -97,6 +131,7 @@ async function canModifyUsers({ adminUser }: { adminUser: AdminUser }): Promise<
 }
 ```
 
+
 ## Customizing the access control based on resource values
 
 In more advanced cases you might need to check access based on record value. 

adminforth/documentation/docs/tutorial/03-Customization/10-menuConfiguration.md

@@ -53,6 +53,32 @@ E.g. create group "Blog" with Items who link to resource "posts" and "categories
 
 If it is rare Group you can make it `open: false` so it would not take extra space in menu, but admin users will be able to open it by clicking on the group name.
 
+## Visibility of menu items
+
+You might want to hide some menu items from the menu for some users. 
+
+To do it use `visible` field in the menu item configuration:
+
+```ts title='./index.ts'
+{
+  ...
+  menu: [
+    {
+      label: 'Categories',
+      icon: 'flowbite:folder-duplicate-outline',
+      resourceId: 'categories',
+//diff-add
+      visible: adminUser => adminUser.dbUser.role === 'admin'
+    },
+  ],
+  ...
+}
+```
+
+> 👆 Please note that this will just hide menu item for non `admin` users, but resource pages will still be available by direct
+> URLs. To limit access, you should also use [allowedActions](/docs/tutorial/Customization/limitingAccess/#disable-full-access-to-resource-based-on-logged-in-user-record-or-role) field in the resource configuration in addition to this.
+
+
 ## Gap
 
 You can put one or several gaps between menu items:

adminforth/documentation/docs/tutorial/03-Customization/13-standardPagesTuning.md

@@ -539,9 +539,9 @@ This way, when creating or editing a record you will be able to choose value for
 
 When foreign resource column is not required, selector will have an 'Unset' option that will set field to `null`. You can change label for this option using `unsetLabel`, like so:
 
-```typescript title="./resources/adminuser.ts"
+```typescript title="./resources/apartments.ts"
 export default {
-      name: 'adminuser',
+      name: 'apartments',
       columns: [
         ...
         {
@@ -558,6 +558,96 @@ export default {
   ],
 ```
 
+### Polymorphic foreign resources
+
+Sometimes it is needed for one column to be a foreign key for multiple tables. For example, given the following schema:
+
+```prisma title="./schema.prisma"
+...
+model apartments {
+  id                String     @id
+  created_at        DateTime?
+  title             String
+  square_meter      Float?
+  price             Decimal
+  number_of_rooms   Int?
+  realtor_id        String?
+}
+
+model houses {
+  id                  String     @id
+  created_at          DateTime?
+  title               String
+  house_square_meter  Float?
+  land_square_meter   Float?
+  price               Decimal
+  realtor_id          String?
+}
+
+model sold_property {
+  id                  String     @id
+  created_at          DateTime?
+  title               String
+  property_id         String
+  realtor_id          String?
+}
+
+```
+
+Here, in `sold_property` table, column `property_id` can be a foreign key for both `apartments` and `houses` tables. If schema is set like this, the is no way to tell to what table exactly `property_id` links to. Also, if defined like usual, adminforth will link to only one of them. To make sure that `property_id` works as intended we need add one more column to `sold_property` and change the way foreign resource is defined in adminforth resource config.
+
+```prisma title="./schema.prisma"
+...
+
+model sold_property {
+  id                  String     @id
+  created_at          DateTime?
+  title               String
+//diff-add
+  property_type       String
+  property_id         String
+  realtor_id          String?
+}
+
+```
+
+`property_type` column will be used to store what table id in `property_id` refers to. And in adminforth config for `sold_property` table, when describing `property_id` column, foreign resource field should be defined as follows:
+
+```typescript title="./resources/sold_property.ts"
+export default {
+      name: 'sold_property',
+      columns: [
+        ...
+        {
+          name: "property_type",
+          showIn: { create: false, edit: false },
+        },
+        {
+          name: "property_id",
+          foreignResource: {
+            polymorphicResources: [
+              {
+                resourceId: 'apartments',
+                whenValue: 'apartment',
+              },
+              {
+                resourceId: 'houses',
+                whenValue: 'house',
+              },
+            ],
+            polymorphicOn: 'property_type',
+          },
+        },
+      ],
+    },
+    ...
+  ],
+```
+
+When defined like this, adminforth will use value in `property_type` to figure out to what table does id in `property_id` refers to and properly link them. When creating or editing a record, adminforth will figure out to what table new `property_id` links to and fill `property_type` on its own using corresponding `whenValue`. Note, that `whenValue` does not have to be the same as `resourceId`, it can be any string as long as they do not repeat withing `polymorphicResources` array. Also, since `whenValue` is a string, column designated as `polymorphicOn` must also be string. Another thing to note is that, `polymorphicOn` column (`property_type` in our case) must not be editable by user, so it must include both `create` and `edit` as `false` in `showIn` value. Even though, `polymorphicOn` column is no editable, it can be beneficial to set is as an enumerator. This will have two benefits: first, columns value displayed in table and show page can be changed to a desired one and second, when filtering on this column, user will only able to choose values provided for him.
+
+If `beforeDatasourceRequest` or `afterDatasourceResponse` hooks are set for polymorphic foreign resource, they will be called for each resource in `polymorphicResources` array.
+
 ## Filtering
 
 ### Filter Options

adminforth/documentation/docs/tutorial/05-Plugins/06-text-complete.md

@@ -37,8 +37,6 @@ export const admin = new AdminForth({
     ...
 //diff-add
     new TextCompletePlugin({
-//diff-add
-      openAiApiKey: process.env.OPENAI_API_KEY as string,
 //diff-add
       fieldName: 'title',
 //diff-add

adminforth/documentation/docs/tutorial/05-Plugins/09-open-signup.md

@@ -103,6 +103,7 @@ export default {
           secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
           //diff-add
         }),
+        //diff-add
       },
     }),
     ...

adminforth/index.ts

@@ -207,29 +207,6 @@ class AdminForth implements IAdminForth {
     return plugins[0] as T;
   }
 
-  validateFieldGroups(fieldGroups: {
-    groupName: string;
-    columns: string[];
-  }[], fieldTypes: {
-    [key: string]: AdminForthResourceColumn;
-}): void {
-    if (!fieldGroups) return;
-    const allColumns = Object.keys(fieldTypes);
-  
-    fieldGroups.forEach((group) => {
-      group.columns.forEach((col) => {
-        if (!allColumns.includes(col)) {
-          const similar = suggestIfTypo(allColumns, col);
-          throw new Error(
-            `Group '${group.groupName}' has an unknown column '${col}'. ${
-              similar ? `Did you mean '${similar}'?` : ''
-            }`
-          );
-        }
-      });
-    });
-  }
-
   validateRecordValues(resource: AdminForthResource, record: any): any {
     // check if record with validation is valid
     for (const column of resource.columns.filter((col) => col.name in record && col.validation)) {
@@ -341,12 +318,6 @@ class AdminForth implements IAdminForth {
         // first find discovered values, but allow override
         res.columns[i] = { ...fieldTypes[col.name], ...col };
       });
-      
-      this.validateFieldGroups(res.options.fieldGroups, fieldTypes);
-      this.validateFieldGroups(res.options.showFieldGroups, fieldTypes);
-      this.validateFieldGroups(res.options.createFieldGroups, fieldTypes);
-      this.validateFieldGroups(res.options.editFieldGroups, fieldTypes);
-
 
       // check if primaryKey column is present
       if (!res.columns.some((col) => col.primaryKey)) {

adminforth/modules/codeInjector.ts

@@ -363,6 +363,14 @@ class CodeInjector implements ICodeInjector {
           }
         });
       }
+
+      if (resource.options?.actions) {
+        resource.options.actions.forEach((action) => {
+          if (action.icon) {
+            icons.push(action.icon);
+          }
+        });
+      }
     });
 
     const uniqueIcons = Array.from(new Set(icons));