unconventional 0.0.2 → 0.0.4

package/dist/core/abstractbase.controller.d.ts

@@ -10,6 +10,7 @@ export default abstract class AbstractBaseController<M extends typeof BaseModel,
     protected _pageLimitDefault: number;
     protected _pageLimitMax: number;
     protected _options: ControllerOptions;
+    /** A controller providing CRUD endpoints for any BaseModel */
     constructor(model: M, options?: ControllerOptions);
     create(options?: ControllerMethodOptions<M, E>): BaseHandler<E>;
     createMany(options?: ControllerMethodOptions<M, E, PI<M>[], I<M>[]>): BaseHandler<E>;
@@ -19,18 +20,50 @@ export default abstract class AbstractBaseController<M extends typeof BaseModel,
     updateMany(options?: ControllerMethodOptions<M, E, PI<M>[], I<M>[]>): BaseHandler<E>;
     delete(options?: ControllerMethodOptions<M, E>): BaseHandler<E>;
     deleteMany(options?: ControllerMethodOptions<M, E, PI<M>[], I<M>[]>): BaseHandler<E>;
+    /**
+     * Creates and returns a new instance of the model M from the provided data. Request body should be a Partial<InstanceType<M>>.
+     * @param req.body - A partial model instance containing all the fields to be modified and their new values.
+     */
     private _create;
+    /**
+     * Creates and returns an array of new instances of the model M from the provided data. Request body should be a Partial<InstanceType<M>>[].
+     * @param req.body - An array of partial model instances containing all the fields to be modified and their new values.
+     */
     private _createMany;
+    /** Gets one instance of the model M.
+     * @param req.params.id - The id or key of a model. If type is a valid ObjectId, lookup will be done with the model's idColumn. Otherwise, keyColumn is used.
+     */
     private _get;
+    /**
+     * Gets all instances (paginated) of the model. Supported query params: limit, cursor, sort.
+     * Default limit is 12. Max limit is 100.
+     */
     private _getAll;
+    /**
+     * Patches all fields in an indicated instance of model M. Certain fields may be restricted.
+     * @param req.params.id - The id or key of a model. If type is a valid ObjectId, lookup will be done with the model's idColumn. Otherwise, keyColumn is used.
+     * @param req.body - A Partial<InstanceType<M>> containing all the fields to be modified and their new values.
+     */
     private _update;
+    /**
+     * Patches all fields in the array of instances of model M. Certain fields may be restricted.
+     * @param req.body - An array of Partial<InstanceType<M>> containing all the fields to be modified and their new values.
+     */
     private _updateMany;
+    /**
+     * Deletes the model with the given identifier.
+     * @param req.params.id - The id or key of a model. If type is a valid ObjectId, lookup will be done with the model's idColumn. Otherwise, keyColumn is used.
+     */
     private _delete;
+    /** Deletes models matching the provided filter. */
     private _deleteMany;
     protected getRequestContext<T extends PI<M> | PI<M>[] = PI<M>>(ctx: Context<E>, hasBody?: boolean): Promise<RequestContext<M, E, T>>;
+    /** Gets the cache namespace for the given request. Route-level cache flags take precedence over controller-level. */
     protected getCache(ctx: Context, controllerLevel: boolean | undefined, routeLevel: boolean | undefined): KVNamespace | undefined;
+    /** Removes the model's private fields from the given response object */
     protected abstract maskPrivateFields(req: RequestContext<M, E>, response: InstanceType<M> | InstanceType<M>[]): Promise<void>;
+    /** Removes the model's uneditable fields from the given request body */
     protected abstract removeSystemFields<T extends PI<M> | PI<M>[] = PI<M>>(req: RequestContext<M, E, T>): void;
+    /** Prevents insecure direct object references (IDOR) */
     protected abstract preventIDOR<T extends PI<M> | PI<M>[] = PI<M>>(req: RequestContext<M, E, T>): Promise<void>;
 }
-//# sourceMappingURL=abstractbase.controller.d.ts.map

package/dist/core/abstractbase.controller.js

@@ -1,14 +1,20 @@
-import { BaseEnvKey, Query } from "../types/api.types";
-import BaseService from "./base.service";
-export default class AbstractBaseController {
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const api_types_1 = require("../types/api.types");
+const base_service_1 = __importDefault(require("./base.service"));
+class AbstractBaseController {
     _model;
     _service;
     _pageLimitDefault = 12;
     _pageLimitMax = 100;
     _options = {};
+    /** A controller providing CRUD endpoints for any BaseModel */
     constructor(model, options) {
         this._model = model;
-        this._service = new BaseService(model);
+        this._service = new base_service_1.default(model);
         this._options = options || {};
     }
     create(options) { return this._create.bind(this, options); }
@@ -19,17 +25,26 @@ export default class AbstractBaseController {
     updateMany(options) { return this._updateMany.bind(this, options); }
     delete(options) { return this._delete.bind(this, options); }
     deleteMany(options) { return this._deleteMany.bind(this, options); }
+    /**
+     * Creates and returns a new instance of the model M from the provided data. Request body should be a Partial<InstanceType<M>>.
+     * @param req.body - A partial model instance containing all the fields to be modified and their new values.
+     */
     async _create(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx);
+        // Pre-processing
         await this.preventIDOR(reqContext);
         if (options?.before)
             await options.before(reqContext);
-        const isPrivileged = ctx.get(BaseEnvKey.isPrivileged);
+        const isPrivileged = ctx.get(api_types_1.BaseEnvKey.isPrivileged);
+        // Avoid overriding owner field if it's privileged user
         if (this._model.ownerField && !(reqContext.body[this._model.ownerField] && isPrivileged)) {
-            const ownerId = ctx.get(BaseEnvKey.ownerId);
+            // Add owner
+            const ownerId = ctx.get(api_types_1.BaseEnvKey.ownerId);
             if (ownerId && this._model.ownerField)
                 reqContext.body[this._model.ownerField] = ownerId;
         }
+        // Configure service
         const config = {
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL,
@@ -37,24 +52,36 @@ export default class AbstractBaseController {
                 constraint: options?.upsertContraint
             }
         };
+        // Request
         let response = await this._service.create(reqContext.body, config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
+        // Response
         return ctx.json(response);
     }
+    /**
+     * Creates and returns an array of new instances of the model M from the provided data. Request body should be a Partial<InstanceType<M>>[].
+     * @param req.body - An array of partial model instances containing all the fields to be modified and their new values.
+     */
     async _createMany(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx);
+        // Pre-processing
         await this.preventIDOR(reqContext);
         if (options?.before)
             await options.before(reqContext);
-        const isPrivileged = ctx.get(BaseEnvKey.isPrivileged);
+        const isPrivileged = ctx.get(api_types_1.BaseEnvKey.isPrivileged);
+        // Avoid overriding owner field if it's privileged user
         reqContext.body.forEach(x => {
             if (this._model.ownerField && !(x[this._model.ownerField] && isPrivileged)) {
-                const ownerId = ctx.get(BaseEnvKey.ownerId);
+                // Add owner
+                const ownerId = ctx.get(api_types_1.BaseEnvKey.ownerId);
                 if (ownerId && this._model.ownerField)
                     x[this._model.ownerField] = ownerId;
             }
         });
+        // Configure service
         const config = {
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL,
@@ -62,25 +89,37 @@ export default class AbstractBaseController {
                 constraint: options?.upsertContraint
             }
         };
+        // Request
         let response = await this._service.createMany(reqContext.body, config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
+        // Response
         return ctx.json(response);
     }
+    /** Gets one instance of the model M.
+     * @param req.params.id - The id or key of a model. If type is a valid ObjectId, lookup will be done with the model's idColumn. Otherwise, keyColumn is used.
+     */
     async _get(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx, false);
+        // Pre-processing
         if (options?.before)
             await options.before(reqContext);
         const identifier = reqContext.params.id;
+        // Configure service
         const config = {
-            expand: reqContext.queries[Query.Expand] || undefined,
+            expand: reqContext.queries[api_types_1.Query.Expand] || undefined,
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL
         };
+        // Request
         let response = await this._service.get(identifier, config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
         await this.maskPrivateFields(reqContext, response);
+        // Download hook
         if (options?.download) {
             const downloadRes = await options.download(reqContext, response);
             const headers = {
@@ -90,89 +129,139 @@ export default class AbstractBaseController {
             return ctx.body(downloadRes.buffer, 200, headers);
         }
         else
+            // Response
             return ctx.json(response);
     }
+    /**
+     * Gets all instances (paginated) of the model. Supported query params: limit, cursor, sort.
+     * Default limit is 12. Max limit is 100.
+     */
     async _getAll(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx, false);
+        // Pre-processing
         if (options?.before)
             await options.before(reqContext);
+        // Configuration
         const queryParams = reqContext.queries;
         let limit = parseInt(queryParams.limit) || this._pageLimitDefault;
         if (limit > this._pageLimitMax && !options?.limitOverride)
             limit = this._pageLimitMax;
+        // Request
         let response = await this._service.getAll({
             limit: limit,
             cursor: queryParams.cursor,
             sort: queryParams.orderBy,
             filter: queryParams.filter,
-            expand: reqContext.queries[Query.Expand] || undefined,
+            expand: reqContext.queries[api_types_1.Query.Expand] || undefined,
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL
         });
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
         await this.maskPrivateFields(reqContext, response);
+        // Response
         return ctx.json(response);
     }
+    /**
+     * Patches all fields in an indicated instance of model M. Certain fields may be restricted.
+     * @param req.params.id - The id or key of a model. If type is a valid ObjectId, lookup will be done with the model's idColumn. Otherwise, keyColumn is used.
+     * @param req.body - A Partial<InstanceType<M>> containing all the fields to be modified and their new values.
+     */
     async _update(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx);
+        // Pre-processing
         await this.preventIDOR(reqContext);
         this.removeSystemFields(reqContext);
         if (options?.before)
             await options.before(reqContext);
         const identifier = reqContext.params.id;
+        // Configure service
         const config = {
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL
         };
+        // Request
         let response = await this._service.update(identifier, reqContext.body, config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
+        // Response
         return ctx.json(response);
     }
+    /**
+     * Patches all fields in the array of instances of model M. Certain fields may be restricted.
+     * @param req.body - An array of Partial<InstanceType<M>> containing all the fields to be modified and their new values.
+     */
     async _updateMany(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx);
+        // Pre-processing
         await this.preventIDOR(reqContext);
         this.removeSystemFields(reqContext);
         if (options?.before)
             await options.before(reqContext);
+        // Configure service
         const config = {
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL
         };
+        // Request
         let response = await this._service.updateMany(reqContext.body, config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
+        // Response
         return ctx.json(response);
     }
+    /**
+     * Deletes the model with the given identifier.
+     * @param req.params.id - The id or key of a model. If type is a valid ObjectId, lookup will be done with the model's idColumn. Otherwise, keyColumn is used.
+     */
     async _delete(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx);
+        // Pre-processing
         if (options?.before)
             await options.before(reqContext);
         const identifier = reqContext.params.id;
+        // Configure service
         const config = {
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL
         };
+        // Request
         let response = await this._service.delete(identifier, config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
+        // Response
         return ctx.json({ success: !!response });
     }
+    /** Deletes models matching the provided filter. */
     async _deleteMany(options, ctx) {
+        // Context
         const reqContext = await this.getRequestContext(ctx);
+        // Pre-processing
         if (options?.before)
             await options.before(reqContext);
+        // Configure service
         const config = {
             filter: reqContext.queries.filter,
             cache: this.getCache(ctx, this._options.cache, options?.cache),
             cacheTTL: this._options.cacheTTL ?? options?.cacheTTL
         };
+        // Request
         let response = await this._service.deleteMany(config);
+        // Post-processing
         if (options?.after)
             await options.after(reqContext, response);
+        // Response
         return ctx.json({ success: !!response });
     }
+    //#region Helpers
     async getRequestContext(ctx, hasBody = true) {
         let body = {};
         if (hasBody) {
@@ -191,8 +280,10 @@ export default class AbstractBaseController {
             get: (key) => { return ctx.get(key); }
         };
     }
+    /** Gets the cache namespace for the given request. Route-level cache flags take precedence over controller-level. */
     getCache(ctx, controllerLevel, routeLevel) {
         const useCache = routeLevel ?? controllerLevel;
         return useCache ? ctx.env.CACHE : undefined;
     }
 }
+exports.default = AbstractBaseController;

package/dist/core/api-error.d.ts

@@ -26,4 +26,3 @@ export declare class APIError extends Error {
     static errTemporarilyUnavailable(message?: string, data?: any, internalProperties?: any): APIError;
     static errServerError(data?: any, internalProperties?: any): APIError;
 }
-//# sourceMappingURL=api-error.d.ts.map

package/dist/core/api-error.js

@@ -1,4 +1,7 @@
-export class APIError extends Error {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIError = void 0;
+class APIError extends Error {
     data;
     internalProperties;
     statusCode;
@@ -76,3 +79,4 @@ export class APIError extends Error {
         return new APIError('Internal Server Error', 'Request could not be carried out.', 500, data, internalProperties);
     }
 }
+exports.APIError = APIError;

package/dist/core/base.cache.d.ts

@@ -5,12 +5,17 @@ export default class BaseCache {
     static get<T>(cache: KVNamespace, key: string): Promise<T | null>;
     static set<T>(cache: KVNamespace, key: string, value: T, ttl?: number): Promise<void>;
     static delete(cache: KVNamespace, key: string): Promise<void>;
+    /**  Sets a model in the cache. Use @param modifier for non-standard responses. */
     static setModel<T extends BaseModel>(cache: KVNamespace, model: T, modifier?: object, ttl?: number): Promise<void>;
+    /** Gets a model from the cache. Use @param modifier for non-standard lookups. */
     static getModel<U extends typeof BaseModel>(cache: KVNamespace, model: U, identifier: string | number, modifier?: object): Promise<InstanceType<U> | null>;
+    /** Deletes a model from the cache. Deletes all modified versions too. */
     static clearModel<T extends BaseModel>(cache: KVNamespace, model: T | undefined): Promise<void>;
+    /**  Sets a page in the cache. Use @param modifier for non-standard responses. */
     static setPage<T extends BaseModel>(cache: KVNamespace, page: T[], modifier?: object, ttl?: number): Promise<void>;
+    /** Gets a page from the cache. Use @param modifier for non-standard lookups. */
     static getPage<U extends typeof BaseModel>(cache: KVNamespace, model: U, modifier?: object): Promise<InstanceType<U>[] | null>;
+    /** Deletes a page from the cache. Deletes all modified versions too. */
     static clearPage<T extends typeof BaseModel>(cache: KVNamespace, model: T): Promise<void>;
     private static getModifier;
 }
-//# sourceMappingURL=base.cache.d.ts.map

package/dist/core/base.cache.js

@@ -1,7 +1,9 @@
-import { CachePrefix, DefaultCacheTTL } from "../types/api.types";
-import { isEmpty } from "../utils/array.utils";
-import { sha256 } from "../utils/crypto.utils";
-export default class BaseCache {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const api_types_1 = require("../types/api.types");
+const array_utils_1 = require("../utils/array.utils");
+const crypto_utils_1 = require("../utils/crypto.utils");
+class BaseCache {
     static kvKeySizeLimit = 512;
     static async get(cache, key) {
         if (key.length > this.kvKeySizeLimit)
@@ -11,62 +13,77 @@ export default class BaseCache {
             return null;
         return JSON.parse(response);
     }
-    static async set(cache, key, value, ttl = DefaultCacheTTL) {
+    static async set(cache, key, value, ttl = api_types_1.DefaultCacheTTL) {
         key.length <= this.kvKeySizeLimit && await cache.put(key, JSON.stringify(value), { expirationTtl: ttl });
     }
     static async delete(cache, key) {
         key.length <= this.kvKeySizeLimit && await cache.delete(key);
     }
+    //#region Model Methods
+    /**  Sets a model in the cache. Use @param modifier for non-standard responses. */
     static async setModel(cache, model, modifier, ttl) {
         const identifier = model?.$id();
         if (!identifier)
             return;
         const modifierTag = await this.getModifier(modifier);
-        await this.set(cache, `${CachePrefix.Record}${model.constructor.name}:${identifier.toString()}:${modifierTag}`, model, ttl);
+        await this.set(cache, `${api_types_1.CachePrefix.Record}${model.constructor.name}:${identifier.toString()}:${modifierTag}`, model, ttl);
         if (model.$key()) {
-            await this.set(cache, `${CachePrefix.Record}${model.constructor.name}:${model.$key()}:${modifierTag}`, model, ttl);
+            await this.set(cache, `${api_types_1.CachePrefix.Record}${model.constructor.name}:${model.$key()}:${modifierTag}`, model, ttl);
         }
     }
+    /** Gets a model from the cache. Use @param modifier for non-standard lookups. */
     static async getModel(cache, model, identifier, modifier) {
         const modifierTag = await this.getModifier(modifier);
-        return await this.get(cache, `${CachePrefix.Record}${model.name}:${identifier.toString()}:${modifierTag}`);
+        return await this.get(cache, `${api_types_1.CachePrefix.Record}${model.name}:${identifier.toString()}:${modifierTag}`);
     }
+    /** Deletes a model from the cache. Deletes all modified versions too. */
     static async clearModel(cache, model) {
         if (!model)
             return;
         const identifier = model?.$id();
         if (!identifier)
             return;
-        const idList = await cache.list({ prefix: `${CachePrefix.Record}${model.constructor.name}:${identifier.toString()}` });
+        // Delete by ID
+        const idList = await cache.list({ prefix: `${api_types_1.CachePrefix.Record}${model.constructor.name}:${identifier.toString()}` });
         const idPromises = idList.keys.map(async (key) => {
             await this.delete(cache, key.name);
         });
+        // Delete by Key
         let keyPromises = [];
         if (model.$key()) {
-            const keyList = await cache.list({ prefix: `${CachePrefix.Record}${model.constructor.name}:${model.$key()}` });
+            const keyList = await cache.list({ prefix: `${api_types_1.CachePrefix.Record}${model.constructor.name}:${model.$key()}` });
             keyPromises = keyList.keys.map(async (key) => {
                 await this.delete(cache, key.name);
             });
         }
+        // Execute
         await Promise.all([...idPromises, ...keyPromises]);
     }
+    //#endregion
+    //#region Page Methods
+    /**  Sets a page in the cache. Use @param modifier for non-standard responses. */
     static async setPage(cache, page, modifier, ttl) {
         if (!page.length)
             return;
         const modifierTag = await this.getModifier(modifier);
-        await this.set(cache, `${CachePrefix.Page}${page[0].constructor.name}:${modifierTag}`, page, ttl);
+        await this.set(cache, `${api_types_1.CachePrefix.Page}${page[0].constructor.name}:${modifierTag}`, page, ttl);
     }
+    /** Gets a page from the cache. Use @param modifier for non-standard lookups. */
     static async getPage(cache, model, modifier) {
         const modifierTag = await this.getModifier(modifier);
-        return await this.get(cache, `${CachePrefix.Page}${model.name}:${modifierTag}`);
+        return await this.get(cache, `${api_types_1.CachePrefix.Page}${model.name}:${modifierTag}`);
     }
+    /** Deletes a page from the cache. Deletes all modified versions too. */
     static async clearPage(cache, model) {
-        const list = await cache.list({ prefix: `${CachePrefix.Page}${model.name}` });
+        const list = await cache.list({ prefix: `${api_types_1.CachePrefix.Page}${model.name}` });
         Promise.all(list.keys.map(async (key) => {
             await this.delete(cache, key.name);
         }));
     }
+    //#endregion
+    //#region Helpers
     static async getModifier(modifier) {
-        return modifier && !isEmpty(modifier) ? await sha256(JSON.stringify(modifier)) : "";
+        return modifier && !(0, array_utils_1.isEmpty)(modifier) ? await (0, crypto_utils_1.sha256)(JSON.stringify(modifier)) : "";
     }
 }
+exports.default = BaseCache;

package/dist/core/base.model.d.ts

@@ -37,4 +37,3 @@ export declare abstract class TimeStamped extends BaseModel {
     updatedAt?: Date;
 }
 export {};
-//# sourceMappingURL=base.model.d.ts.map