remult 0.25.6-exp.1 → 0.25.6-exp.3

package/esm/server/expressBridge.js

@@ -316,6 +316,8 @@ export class RemultServerImplementation {
     }
     async getRemult(req) {
         let remult;
+        if (!req)
+            return await this.runWithRemult(async (c) => (remult = c));
         await this.process(async (c) => {
             remult = c;
         })(req, undefined);

package/esm/src/filter/filter-interfaces.js

@@ -1,18 +1,11 @@
 import { getEntityRef, getEntitySettings } from '../remult3/getEntityRef.js';
 import { getRelationFieldInfo } from '../remult3/relationInfoMember.js';
+/**
+ * The `Filter` class is a helper class that focuses on filter-related concerns. It provides methods
+ * for creating and applying filters in queries.
+ */
 export class Filter {
     apply;
-    constructor(apply) {
-        this.apply = apply;
-    }
-    __applyToConsumer(add) {
-        this.apply(add);
-    }
-    static async resolve(filter) {
-        if (typeof filter === 'function')
-            return await filter();
-        return filter;
-    }
     static createCustom(rawFilterTranslator, key = '') {
         let rawFilterInfo = { key: key, rawFilterTranslator };
         return Object.assign((x) => {
@@ -26,6 +19,58 @@ export class Filter {
             };
         }, { rawFilterInfo });
     }
+    /**
+     * Translates an `EntityFilter` to a plain JSON object that can be stored or transported.
+     *
+     * @template T The entity type for the filter.
+     * @param {EntityMetadata<T>} entityDefs The metadata of the entity associated with the filter.
+     * @param {EntityFilter<T>} where The `EntityFilter` to be translated.
+     * @returns {any} A plain JSON object representing the `EntityFilter`.
+     *
+     * @example
+     * // Assuming `Task` is an entity class
+     * const jsonFilter = Filter.entityFilterToJson(Task, { completed: true });
+     * // `jsonFilter` can now be stored or transported as JSON
+     */
+    static entityFilterToJson(entityDefs, where) {
+        return Filter.fromEntityFilter(entityDefs, where).toJson();
+    }
+    /**
+     * Translates a plain JSON object back into an `EntityFilter`.
+     *
+     * @template T The entity type for the filter.
+     * @param {EntityMetadata<T>} entityDefs The metadata of the entity associated with the filter.
+     * @param {any} packed The plain JSON object representing the `EntityFilter`.
+     * @returns {EntityFilter<T>} The reconstructed `EntityFilter`.
+     *
+     * @example
+     * // Assuming `Task` is an entity class and `jsonFilter` is a JSON object representing an EntityFilter
+     * const taskFilter = Filter.entityFilterFromJson(Task, jsonFilter);
+     * // Using the reconstructed `EntityFilter` in a query
+     * const tasks = await remult.repo(Task).find({ where: taskFilter });
+     * for (const task of tasks) {
+     *   // Do something for each task based on the filter
+     * }
+     */
+    static entityFilterFromJson(entityDefs, packed) {
+        return buildFilterFromRequestParameters(entityDefs, {
+            get: (key) => packed[key],
+        });
+    }
+    /**
+     * Converts an `EntityFilter` to a `Filter` that can be used by the `DataProvider`. This method is
+     * mainly used internally.
+     *
+     * @template T The entity type for the filter.
+     * @param {EntityMetadata<T>} entity The metadata of the entity associated with the filter.
+     * @param {EntityFilter<T>} whereItem The `EntityFilter` to be converted.
+     * @returns {Filter} A `Filter` instance that can be used by the `DataProvider`.
+     *
+     * @example
+     * // Assuming `Task` is an entity class and `taskFilter` is an EntityFilter
+     * const filter = Filter.fromEntityFilter(Task, taskFilter);
+     * // `filter` can now be used with the DataProvider
+     */
     static fromEntityFilter(entity, whereItem) {
         let result = [];
         for (const key in whereItem) {
@@ -122,19 +167,25 @@ export class Filter {
         }
         return new AndFilter(...result);
     }
+    constructor(apply) {
+        this.apply = apply;
+    }
+    __applyToConsumer(add) {
+        this.apply(add);
+    }
+    //@internal
+    static async resolve(filter) {
+        if (typeof filter === 'function')
+            return await filter();
+        return filter;
+    }
+    //@internal
     toJson() {
         let r = new FilterSerializer();
         this.__applyToConsumer(r);
         return r.result;
     }
-    static entityFilterToJson(entityDefs, where) {
-        return Filter.fromEntityFilter(entityDefs, where).toJson();
-    }
-    static entityFilterFromJson(entityDefs, packed) {
-        return buildFilterFromRequestParameters(entityDefs, {
-            get: (key) => packed[key],
-        });
-    }
+    //@internal
     static async translateCustomWhere(r, entity, remult) {
         let f = new customTranslator(async (filterKey, custom) => {
             let r = [];

package/esm/src/live-query/SubscriptionChannel.js

@@ -101,11 +101,41 @@ export class LiveQuerySubscriber {
     }
 }
 export const liveQueryKeepAliveRoute = '_liveQueryKeepAlive';
+/**
+ * The `SubscriptionChannel` class is used to send messages from the backend to the frontend,
+ * using the same mechanism used by live queries.
+ *
+ * @template messageType The type of the message that the channel will handle.
+ * @example
+ * // Defined in code that is shared between the frontend and the backend
+ * const statusChange = new SubscriptionChannel<{ oldStatus: number, newStatus: number }>("statusChange");
+ *
+ * // Backend: Publishing a message
+ * statusChange.publish({ oldStatus: 1, newStatus: 2 });
+ *
+ * // Frontend: Subscribing to messages
+ * statusChange.subscribe((message) => {
+ *     console.log(`Status changed from ${message.oldStatus} to ${message.newStatus}`);
+ * });
+ *
+ * // Note: If you want to publish from the frontend, use a BackendMethod for that.
+ */
 export class SubscriptionChannel {
     channelKey;
+    /**
+     * Constructs a new `SubscriptionChannel` instance.
+     *
+     * @param {string} channelKey The key that identifies the channel.
+     */
     constructor(channelKey) {
         this.channelKey = channelKey;
     }
+    /**
+     * Publishes a message to the channel. This method should only be used on the backend.
+     *
+     * @param {messageType} message The message to be published.
+     * @param {Remult} [remult] An optional instance of Remult to use for publishing the message.
+     */
     publish(message, remult) {
         remult = remult || defaultRemult;
         remult.subscriptionServer.publishMessage(this.channelKey, message);

package/esm/src/remult3/remult3.js

@@ -9,116 +9,76 @@ export {};
   * review react summit
 #
 
-//y1 - support get with backend method, with url search params as the first parameter, & url as second parameter
-//y1 - admin url!
+//y1 - getFields didn't work for kobi in the home component
+//y1 - talk about export api is not possible in +server - how did we face that in others, and how do we doc it - ended up using _api
 //y1 - number default storage in knex is decimal and it by default has 8,2 - meaning only 999,999 - I think it should be way bigger than that. in firefly we do at least 18 - https://discord.com/channels/975754286384418847/1195162533447876658
-//y1 - talk about the parameter issue with backend methods
+//y1 - admin url!
+//y1 - consider sql expression gets a dbnames of it's own (that already has the "tableName" defined correctly) maybe also the filter translator
+//y1 - talk about modules in init express with entities/controllers,initRequest,initApi
 //y1 - tried to upgrade vitest, nuxt tests are failing with loading uuid - sounds familiar?
-//y1 - I think that the tests you've setup cover next app router - I added to the setup, but not sure where else
+//y1 - I think that the tests you've setup don't cover next app router - I added to the setup, but not sure where else
+//y1 - support get with backend method, with url search params as the first parameter, & url as second parameter
+//y1 - talk about the parameter issue with backend methods
 //y1 - select data provider per entity https://discord.com/channels/975754286384418847/976006081748807690/1201415305885397003
-//y1 - talk about modules in init express with entities/controllers,initRequest,initApi
+//y2 - live query refresh of view on table update
+//y2 - livequery for findfirst (@JY)
 
+/*y2 -
+//y2 - allow api update only for new rows
+  @Fields.string<Category>({
+    allowApiUpdate: (c) => getEntityRef(c).isNew(),
+  })
+  Description = ""*/
+//y2 - get backend methods to work when specifying types for date, and entities as poco's
+//y2 - conside law-q db based on schema issue - I think that while running the dataProvider function, we should have a valid remult - maybe even have a valid remult, that will be valid until api is run
+//y2 - #239 - (@JY) add a way to get from fieldMetadata back to entity repo (like we have in fieldRef)
+//y2 - constraints (@JY)
+// remult admin
 //p1 - Small thing, I get SvelteKitError: Not found: /vite.svg
 //p1 - understand the to many relation for the admin, based on the to one
 //p1 - relation from order details to order gave a compound id info - and it is not true - same for the relation to product
-//p1 - live query with include
 //p1 - new row when there are relations, looks funny (see product)
 //p1 - the + row in the bottom should extend to the full width
+//p1 - need a way to extract the fields from the relation - for generating relation based sql
+//p1 - allow conditional admin - like allowed
+//p1 - remult-admin doesn't handle primary key that has compound column
+//p1 - remult-admin didn't show a update for a table with a uniqua that is numeric
+//remult
+//p1 - better support union types (status, etc... so it'll work also in filter etc...)
+//p1 - add tablename parameter for dbNamesOf
+//p1 -check if count doesn't respect allow read (I think)
+//p1 - when a tasks table exists in a different schema - we get many errors
+//p1 - live query with include
 //p1 - adjust angular tutorial starter kit for latest angular (as is in tutorial)
-
-/*y2 -
-  @Fields.string<Category>({
-    allowApiUpdate: (c) => getEntityRef(c).isNew(),
-  })
-  Description = ""*/
+//p2 - I think there should be a way to throw a forbidden exception
+//p2 - processError in remult express
+//p2 - allow find options preprocessor for api calls, to use for authorization
+//p2 - when subscribe is forbidden - the query still runs after the renew process
+//p2 - 'update tasks set  where id = $1
+//p1 - ValueListFieldType - the decorator gives an error in react vite project - see langulage yedidya
+//p2 - type metadata.key - to keyof entity - based on cwis input
+//y2 - remove __dirname from tutorials
+//p2 - when value changes for field with error, clear error - so the user will feel comfortable
+//p2 - allowApiUpdate should be false for include in api false
+//docs
+//p2 - make sure that internal members do not appear in the documentation - try running it on the d.ts instead of the code itself.
+//------
 //y2 - from the crm-demo(https://crm-demo.up.railway.app/deals), after editing a deal: - _updateEntityBasedOnApi
 //y2 - Backend methods are transactions, it's not intuitive and maybe should be optional / opt in
 //y2 - how to run a transaction as a user
 //p2 - enum column
-//p2 - I think there should be a way to throw a forbidden exception
-//y2 - get backend methods to work when specifying types for date, and entities as poco's
-//y2 - required
-//y2 - reconsider validators
 //y2 - message for invalid value
 //y2 - message for relation that is missing
-//p2 - more column types
-//p2 -   processError in remult express
-//p2 -   allow find options preprocessor for api calls, to use for authorization
-//p2 - write doc about controlling updates of rows...
-//p1 - need a way to extract the fields from the relation - for generating relation based sql
-//p1 - when doing this, work on graphql relation with fields not just field
-//p2 - add docs for apply changes
-//p2 - when subscribe is forbidden - the query still runs after the renew process
-//p2 - 'update tasks set  where id = $1
 //y2 - consider multi tenancies
 //y2 - allow api read to also support instance and filter. - problem with promise
-//p2 - doc this:
-/**
- * //p2 - doc this
-remult.apiClient.httpClient = (
-  input: RequestInfo | URL,
-  init?: RequestInit
-  ) => {
-    return fetch(input, {
-      ...init,
-      headers: {
-        authorization: 'Bearer ' + sessionStorage.sessionId,
-      },
-      cache: 'no-store',
-    })
-}
-
-&&
-remult.apiClient.url='localhost:3007/api
-
-
-*/
-//p1 - allow conditional admin - like allowed
-//p1 - remult-admin doesn't handle primary key that has compound column
-//p1 - remult-admin didn't show a update for a table with a uniqua that is numeric
-//p1 -check if checouknt doesn't respect allow read (I think)
-//p1 - when a tasks table exists in a different schema - we get many errors
-//p1 - allow api update only for new rows
-//p1 - getFields didn't work for kobi in the home component
-//p1 - add to docs  https://codesandbox.io/p/devbox/demo-sql-expression-wqvj4g
-//p1 - ValueListFieldType - the decorator gives an error in react vite project - see langulage yedidya
-//y1 - talk about export api is not possible in +server - how did we face that in others, and how do we doc it
+//p2 - more column types
 //p2 - document validators
 //p2 - and validators to reference
 //y2 - discuss a default date formatter
 //y2 - add some api testing framework for user unit tests (will help with codesandbox based discussions)
-//y2 - live query refresh of view on table update
-//y2 - livequery for findfirst (@JY)
-//y2 - #239 - (@JY) add a way to get from fieldMetadata back to entity repo (like we have in fieldRef)
-//p2 - constraints (@JY)
-//p2 - type metadata.key - to keyof entity - based on cwis input
-//y2 - remove __dirname from tutorials
-//p2 - when value changes for field with error, clear error - so the user will feel comfortable
-//p2 - conside law-q db based on schema issue - I think that while running the dataProvider function, we should have a valid remult - maybe even have a valid remult, that will be valid until api is run
-//y2 - we should really reconsider allow null by default to be true - I think that what we're doing is confusing for most . In my case I added a volunteer relation, and didn't set any value to it - and I get an error that null value is not allowed for it
-//p1 - add a follow up doc to the tutorial on how to user a real user table for the users
-/**
-* our default is allow null false.
-* for sql databases we add a db default of 0/''/false
-* when we set a relation to null - we update the related field to null
-* we do not enforce allow null false (mongo, json it'll get stored)
-
- */
-//p2 - allowApiUpdate should be false for include in api false
 //[ ] V2 - what to do about for relations count?
 //[ ] V2 - condition? not to fetch if null etc....
 //[ ] V3 - all these fields will also appear in the where etc... in the typescript api - but we will not enforce them
 //y2 - consider if field types should include validation in them by default (string,number that it's not NaN etc...) and if so, what message?
 //y2 - should enforce integer - currently we probably round / truncate it
 //p1 - adjust react tutorial to esm
-//p1 - write docs on with remult - and usage in init api
-//p1 - document value converter - including field type in the db
-/*y1 - discuss sql stuff:
-     https://discord.com/channels/975754286384418847/975754286384418852/1198997156678357043
-     https://codesandbox.io/p/devbox/demo-sql-expression-forked-f94p6m?file=%2Fsrc%2Findex.ts%3A21%2C3-21%2C12&workspaceId=c0f7eccf-c151-423b-ac8e-0f0f3e1ad350
-     https://codesandbox.io/p/devbox/demo-sql-expression-forked-c2jhyc?file=%2Fsrc%2Findex.ts%3A37%2C50&workspaceId=7e9d0505-ea79-46f1-8973-50cadde4fa96
-
-
-*/
-//p1 - make dbNames of have a default wrapIdentifier based on the current data provider
-//p1 - prevent circular in sql expression

package/esm/src/sort.js

@@ -1,6 +1,15 @@
 import { CompoundIdField } from './CompoundIdField.js';
 import { getRelationFieldInfo } from './remult3/relationInfoMember.js';
+/**
+ * The `Sort` class is used to describe sorting criteria for queries. It is mainly used internally,
+ * but it provides a few useful functions for working with sorting.
+ */
 export class Sort {
+    /**
+     * Translates the current `Sort` instance into an `EntityOrderBy` object.
+     *
+     * @returns {EntityOrderBy<any>} An `EntityOrderBy` object representing the sort criteria.
+     */
     toEntityOrderBy() {
         let result = {};
         for (const seg of this.Segments) {
@@ -12,10 +21,25 @@ export class Sort {
         }
         return result;
     }
+    /**
+     * Constructs a `Sort` instance with the provided sort segments.
+     *
+     * @param {...SortSegment[]} segments The sort segments to be included in the sort criteria.
+     */
     constructor(...segments) {
         this.Segments = segments;
     }
+    /**
+     * The segments of the sort criteria.
+     *
+     * @type {SortSegment[]}
+     */
     Segments;
+    /**
+     * Reverses the sort order of the current sort criteria.
+     *
+     * @returns {Sort} A new `Sort` instance with the reversed sort order.
+     */
     reverse() {
         let r = new Sort();
         for (const s of this.Segments) {
@@ -23,6 +47,14 @@ export class Sort {
         }
         return r;
     }
+    /**
+     * Compares two objects based on the current sort criteria.
+     *
+     * @param {any} a The first object to compare.
+     * @param {any} b The second object to compare.
+     * @param {function(FieldMetadata): string} [getFieldKey] An optional function to get the field key for comparison.
+     * @returns {number} A negative value if `a` should come before `b`, a positive value if `a` should come after `b`, or zero if they are equal.
+     */
     compare(a, b, getFieldKey) {
         if (!getFieldKey)
             getFieldKey = (x) => x.key;
@@ -43,6 +75,14 @@ export class Sort {
         }
         return r;
     }
+    /**
+     * Translates an `EntityOrderBy` to a `Sort` instance.
+     *
+     * @template T The entity type for the order by.
+     * @param {EntityMetadata<T>} entityDefs The metadata of the entity associated with the order by.
+     * @param {EntityOrderBy<T>} [orderBy] The `EntityOrderBy` to be translated.
+     * @returns {Sort} A `Sort` instance representing the translated order by.
+     */
     static translateOrderByToSort(entityDefs, orderBy) {
         if (!orderBy)
             return undefined;
@@ -86,6 +126,15 @@ export class Sort {
             }
         return sort;
     }
+    /**
+     * Creates a unique `Sort` instance based on the provided `Sort` and the entity metadata.
+     * This ensures that the sort criteria result in a unique ordering of entities.
+     *
+     * @template T The entity type for the sort.
+     * @param {EntityMetadata<T>} entityMetadata The metadata of the entity associated with the sort.
+     * @param {Sort} [orderBy] The `Sort` instance to be made unique.
+     * @returns {Sort} A `Sort` instance representing the unique sort criteria.
+     */
     static createUniqueSort(entityMetadata, orderBy) {
         if ((!orderBy || Object.keys(orderBy).length === 0) &&
             entityMetadata.options.defaultOrderBy)
@@ -104,6 +153,15 @@ export class Sort {
         }
         return orderBy;
     }
+    /**
+     * Creates a unique `EntityOrderBy` based on the provided `EntityOrderBy` and the entity metadata.
+     * This ensures that the order by criteria result in a unique ordering of entities.
+     *
+     * @template T The entity type for the order by.
+     * @param {EntityMetadata<T>} entityMetadata The metadata of the entity associated with the order by.
+     * @param {EntityOrderBy<T>} [orderBy] The `EntityOrderBy` to be made unique.
+     * @returns {EntityOrderBy<T>} An `EntityOrderBy` representing the unique order by criteria.
+     */
     static createUniqueEntityOrderBy(entityMetadata, orderBy) {
         if (!orderBy || Object.keys(orderBy).length === 0)
             orderBy = entityMetadata.options.defaultOrderBy;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "remult",
-    "version": "0.25.6-exp.1",
+    "version": "0.25.6-exp.3",
     "description": "A CRUD framework for full-stack TypeScript",
     "homepage": "https://remult.dev",
     "repository": {

package/server/expressBridge.d.ts

@@ -74,7 +74,7 @@ export interface RemultServer<RequestType> extends RemultServerCore<RequestType>
     withRemultAsync<T>(request: RequestType | undefined, what: () => Promise<T>): Promise<T>;
 }
 export interface RemultServerCore<RequestType> {
-    getRemult(req: RequestType): Promise<Remult>;
+    getRemult(req?: RequestType): Promise<Remult>;
     openApiDoc(options: {
         title: string;
         version?: string;

package/server/expressBridge.js

@@ -597,13 +597,19 @@ var RemultServerImplementation = /** @class */ (function () {
             var _this = this;
             return tslib_1.__generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.process(function (c) { return tslib_1.__awaiter(_this, void 0, void 0, function () {
+                    case 0:
+                        if (!!req) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.runWithRemult(function (c) { return tslib_1.__awaiter(_this, void 0, void 0, function () { return tslib_1.__generator(this, function (_a) {
+                                return [2 /*return*/, (remult = c)];
+                            }); }); })];
+                    case 1: return [2 /*return*/, _a.sent()];
+                    case 2: return [4 /*yield*/, this.process(function (c) { return tslib_1.__awaiter(_this, void 0, void 0, function () {
                             return tslib_1.__generator(this, function (_a) {
                                 remult = c;
                                 return [2 /*return*/];
                             });
                         }); })(req, undefined)];
-                    case 1:
+                    case 3:
                         _a.sent();
                         return [2 /*return*/, remult];
                 }

package/src/column-interfaces.d.ts

@@ -165,15 +165,100 @@ export interface FieldMetadata<valueType = any, entityType = any> {
      */
     fromInput(inputValue: string, inputType?: string): valueType;
 }
+/**
+ * Interface for converting values between different formats, such as in-memory objects, database storage,
+ * JSON data transfer objects (DTOs), and HTML input elements.
+ *
+ * @template valueType The type of the value that the converter handles.
+ */
 export interface ValueConverter<valueType> {
+    /**
+     * Converts a value from a JSON DTO to the valueType. This method is typically used when receiving data
+     * from a REST API call or deserializing a JSON payload.
+     *
+     * @param val The value to convert.
+     * @returns The converted value.
+     *
+     * @example
+     * fromJson: val => new Date(val)
+     */
     fromJson?(val: any): valueType;
+    /**
+     * Converts a value of valueType to a JSON DTO. This method is typically used when sending data
+     * to a REST API or serializing an object to a JSON payload.
+     *
+     * @param val The value to convert.
+     * @returns The converted value.
+     *
+     * @example
+     * toJson: val => val?.toISOString()
+     */
     toJson?(val: valueType): any;
+    /**
+     * Converts a value from the database format to the valueType.
+     *
+     * @param val The value to convert.
+     * @returns The converted value.
+     *
+     * @example
+     * fromDb: val => new Date(val)
+     */
     fromDb?(val: any): valueType;
+    /**
+     * Converts a value of valueType to the database format.
+     *
+     * @param val The value to convert.
+     * @returns The converted value.
+     *
+     * @example
+     * toDb: val => val?.toISOString()
+     */
     toDb?(val: valueType): any;
+    /**
+     * Converts a value of valueType to a string suitable for an HTML input element.
+     *
+     * @param val The value to convert.
+     * @param inputType The type of the input element (optional).
+     * @returns The converted value as a string.
+     *
+     * @example
+     * toInput: (val, inputType) => val?.toISOString().substring(0, 10)
+     */
     toInput?(val: valueType, inputType?: string): string;
+    /**
+     * Converts a string from an HTML input element to the valueType.
+     *
+     * @param val The value to convert.
+     * @param inputType The type of the input element (optional).
+     * @returns The converted value.
+     *
+     * @example
+     * fromInput: (val, inputType) => new Date(val)
+     */
     fromInput?(val: string, inputType?: string): valueType;
+    /**
+     * Returns a displayable string representation of a value of valueType.
+     *
+     * @param val The value to convert.
+     * @returns The displayable string.
+     *
+     * @example
+     * displayValue: val => val?.toLocaleDateString()
+     */
     displayValue?(val: valueType): string;
+    /**
+     * Specifies the storage type used in the database for this field.
+     *
+     * @example
+     * readonly fieldTypeInDb = 'decimal(18,2)';
+     */
     readonly fieldTypeInDb?: string;
+    /**
+     * Specifies the type of HTML input element suitable for values of valueType.
+     *
+     * @example
+     * readonly inputType = 'date';
+     */
     readonly inputType?: string;
 }
 export declare type FieldValidator<entityType = any, valueType = any> = (entity: entityType, event: ValidateFieldEvent<entityType, valueType>) => boolean | string | void | undefined | Promise<boolean | string | void | undefined>;

package/src/context.d.ts

@@ -76,19 +76,76 @@ export declare class Remult {
 export type GetArguments<T> = T extends (...args: infer FirstArgument) => any ? FirstArgument : never;
 export interface RemultContext {
 }
+/**
+ * Interface for configuring the API client used by Remult to perform HTTP calls to the backend.
+ */
 export interface ApiClient {
-    /** The http client to use when making api calls.
+    /**
+     * The HTTP client to use when making API calls. It can be set to a function with the `fetch` signature
+     * or an object that has `post`, `put`, `delete`, and `get` methods. This can also be used to inject
+     * logic before each HTTP call, such as adding authorization headers.
+     *
      * @example
+     * // Using Axios
      * remult.apiClient.httpClient = axios;
+     *
+     * @example
+     * // Using Angular HttpClient
+     * remult.apiClient.httpClient = httpClient;
+     *
      * @example
-     * remult.apiClient.httpClient = httpClient;//angular http client
+     * // Using fetch (default)
+     * remult.apiClient.httpClient = fetch;
+     *
      * @example
-     * remult.apiClient.httpClient = fetch; //this is the default
+     * // Adding bearer token authorization
+     * remult.apiClient.httpClient = (input: RequestInfo | URL, init?: RequestInit) => {
+     *   return fetch(input, {
+     *     ...init,
+     *     headers: {
+     *       authorization: 'Bearer ' + sessionStorage.sessionId,
+     *     },
+     *     cache: 'no-store',
+     *   });
+     * };
      */
     httpClient?: ExternalHttpProvider | typeof fetch;
-    /** The base url to for making api calls */
+    /**
+     * The base URL for making API calls. By default, it is set to '/api'. It can be modified to be relative
+     * or to use a different domain for the server.
+     *
+     * @example
+     * // Relative URL
+     * remult.apiClient.url = './api';
+     *
+     * @example
+     * // Different domain
+     * remult.apiClient.url = 'https://example.com/api';
+     */
     url?: string;
+    /**
+     * The subscription client used for real-time data updates. By default, it is set to use Server-Sent Events (SSE).
+     * It can be set to any subscription provider as illustrated in the Remult tutorial for deploying to a serverless environment.
+     *
+     * @see https://remult.dev/tutorials/react-next/deployment.html#deploying-to-a-serverless-environment
+     */
     subscriptionClient?: SubscriptionClient;
+    /**
+     * A function that wraps message handling for subscriptions. This is useful for executing some code before
+     * or after any message arrives from the subscription. For example, in Angular, this can be used to trigger
+     * a render by calling the `NgZone` run method.
+     *
+     * @example
+     * // Angular example
+     * import { Component, NgZone } from '@angular/core';
+     * import { remult } from "remult";
+     *
+     * export class AppComponent {
+     *   constructor(zone: NgZone) {
+     *     remult.apiClient.wrapMessageHandling = handler => zone.run(() => handler());
+     *   }
+     * }
+     */
     wrapMessageHandling?: (x: VoidFunction) => void;
 }
 export interface ControllerOptions {