xpref 1.0.0

package/api-docs/body-schema.d.ts

@@ -0,0 +1 @@
+export default function getBodySchemas(props: any): any;

package/api-docs/body-schema.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getBodySchemas;
+const utils_1 = require("../utils");
+const schemaFromString = (name) => {
+    const [schemaName, required] = (0, utils_1.decodeSchemaName)(name);
+    return {
+        [schemaName]: {
+            schema: { $ref: `#components/schemas/${schemaName}` },
+            required,
+        },
+    };
+};
+const getSchemasOfArrayProperties = (properties) => properties
+    .reduce((accu, item) => {
+    const isString = typeof item === 'string';
+    if (isString)
+        return { ...accu, ...schemaFromString(item) };
+    return accu;
+}, {});
+const getSchemasOfProperties = (properties) => {
+    const isArray = Array.isArray(properties);
+    if (!isArray)
+        return properties;
+    return getSchemasOfArrayProperties(properties);
+};
+function getBodySchemas(props) {
+    const { properties } = props;
+    const nextProps = getSchemasOfProperties(properties);
+    return { ...props, properties: nextProps };
+}

package/api-docs/index.d.ts

@@ -0,0 +1,3 @@
+import type { APIDocs, APIDocsProps, APIDocsOptions } from './types';
+export default function setupApiDocs(apiDocs: APIDocsProps, options: APIDocsOptions): APIDocs;
+export * from './types';

package/api-docs/index.js

@@ -0,0 +1,49 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = setupApiDocs;
+const swagger_ui_express_1 = require("swagger-ui-express");
+const security_1 = __importDefault(require("./security"));
+const path_1 = __importDefault(require("./path"));
+const schema_1 = __importDefault(require("./schema"));
+const getTags = (tags) => {
+    const tagNames = Object.keys(tags);
+    return tagNames.reduce((acc, name) => {
+        const tag = tags[name] || {};
+        return [...acc, { name, ...tag }];
+    }, []);
+};
+function setupApiDocs(apiDocs, options) {
+    const { routes, schemas } = options;
+    const { bearerAuth = false, tags = {}, apiKeys = [], } = apiDocs;
+    const [securitySchemas, security] = (0, security_1.default)({ bearerAuth, apiKeys });
+    const touchedSchemas = (0, schema_1.default)(schemas);
+    const components = { schemas: touchedSchemas, ...securitySchemas };
+    const paths = (0, path_1.default)(routes);
+    const docs = {
+        openapi: '3.0.0',
+        ...apiDocs,
+        paths,
+        tags: getTags(tags),
+        components,
+        security,
+    };
+    return [swagger_ui_express_1.serve, (0, swagger_ui_express_1.setup)(docs)];
+}
+__exportStar(require("./types"), exports);

package/api-docs/parameter-schema.d.ts

@@ -0,0 +1 @@
+export default function getParameterSchemas(routeParams: any): any[];

package/api-docs/parameter-schema.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getParameterSchemas;
+const utils_1 = require("../utils");
+const schemaFromString = (name, whereToBe = '') => {
+    const [schemaName, required] = (0, utils_1.decodeSchemaName)(name);
+    return {
+        name: schemaName,
+        schema: { $ref: `#components/schemas/${schemaName}` },
+        in: whereToBe,
+        required,
+    };
+};
+const inlineSchema = (schema, whereToBe = '') => {
+    const [name, props] = schema;
+    const [schemaName, required] = (0, utils_1.decodeSchemaName)(name);
+    const type = props.type || 'string';
+    if (type !== 'object')
+        return {
+            name: schemaName,
+            required,
+            in: whereToBe,
+            ...props,
+        };
+    return {
+        name: schemaName,
+        parameters: getObjectSchema({ name: schemaName, ...props }, whereToBe),
+    };
+};
+const getSchemasOfObjectProperties = (properties, _whereToBe = '') => properties;
+const getSchemasOfArrayProperties = (properties, whereToBe = '') => properties.map((name) => {
+    const isString = typeof name === 'string';
+    if (isString)
+        return schemaFromString(name, whereToBe);
+    return inlineSchema(name, whereToBe);
+});
+const getObjectSchema = (schema, whereToBe = '') => {
+    const type = schema.type || 'string';
+    if (type !== 'object')
+        return [{ type, ...schema, in: whereToBe }];
+    const { properties } = schema;
+    const isArray = Array.isArray(properties);
+    if (isArray)
+        return getSchemasOfArrayProperties(properties, whereToBe);
+    return getSchemasOfObjectProperties(properties, whereToBe);
+};
+function getParameterSchemas(routeParams) {
+    const { headers = [], params = [], query = [] } = routeParams;
+    const headersSchema = { type: 'object', properties: headers, name: 'headers' };
+    const paramsSchema = { type: 'object', properties: params, name: 'params' };
+    const querySchema = { type: 'object', properties: query, name: 'query' };
+    return [
+        ...getObjectSchema(headersSchema, 'headers'),
+        ...getObjectSchema(paramsSchema, 'path'),
+        ...getObjectSchema(querySchema, 'query'),
+    ];
+}

package/api-docs/path-schema.d.ts

@@ -0,0 +1 @@
+export declare const getMethodParameters: (methodHandler: any) => {};

package/api-docs/path-schema.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMethodParameters = void 0;
+const parameter_schema_1 = __importDefault(require("./parameter-schema"));
+const body_schema_1 = __importDefault(require("./body-schema"));
+const getMethodParameters = (methodHandler) => {
+    if (Array.isArray(methodHandler))
+        return {};
+    if (typeof methodHandler === 'function')
+        return {};
+    const { params } = methodHandler;
+    const parameters = {
+        parameters: (0, parameter_schema_1.default)(params),
+    };
+    const { body = [] } = params;
+    if (body.length === 0)
+        return parameters;
+    const content = {
+        'application/json': {
+            schema: (0, body_schema_1.default)({
+                type: 'object',
+                properties: body,
+            }),
+        },
+    };
+    return { ...parameters, requestBody: { content } };
+};
+exports.getMethodParameters = getMethodParameters;

package/api-docs/path.d.ts

@@ -0,0 +1,2 @@
+import type { Route } from '../types';
+export default function getPaths(routes: Route): any;

package/api-docs/path.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getPaths;
+const path_schema_1 = require("./path-schema");
+const defaultResponse = {
+    200: {
+        description: 'Operation completed successfully.',
+    },
+};
+const decodePath = (path) => path.replace(/:(\w*)/g, '{$1}');
+const getMethodDescription = (methodHandler = {}) => {
+    if (Array.isArray(methodHandler) || typeof methodHandler === 'function') {
+        return {};
+    }
+    const { description = [] } = methodHandler;
+    const [summary, desc = ''] = Array.isArray(description) ? description : [description, ''];
+    return { summary, description: desc };
+};
+const getResponses = (methodProps = {}) => {
+    const { responses = {} } = methodProps;
+    const allResponse = { ...defaultResponse, ...responses };
+    return Object.entries(allResponse).reduce((accu, response) => {
+        const [code, res] = response;
+        const touchedResponse = { contentType: 'application/json', ...res };
+        return { ...accu, [code]: touchedResponse };
+    }, {});
+};
+const getMethodPath = (tag, methodProps) => {
+    const desc = getMethodDescription(methodProps);
+    const params = (0, path_schema_1.getMethodParameters)(methodProps);
+    const responses = getResponses(methodProps);
+    return {
+        responses,
+        tags: [tag],
+        ...desc,
+        ...params,
+    };
+};
+const generateMethodsPath = (props, { tag }) => {
+    const methods = Object.keys(props);
+    return methods.reduce((carry, method) => {
+        const methodDetail = props[method];
+        const result = {
+            ...carry,
+            [method]: getMethodPath(tag, methodDetail),
+        };
+        return result;
+    }, {});
+};
+const generatePath = (pPath, pathProps, { parentTag = false } = {}) => {
+    const path = decodePath(pPath);
+    const [tag, middlewares, methodHandler, children = {}] = pathProps;
+    const curTag = parentTag || tag;
+    const result = {
+        [path]: generateMethodsPath(methodHandler, { tag: curTag, middlewares }),
+    };
+    const childPaths = Object.keys(children);
+    if (childPaths.length === 0)
+        return result;
+    const paths = childPaths.reduce((carry, childPath) => {
+        const childProps = children[childPath];
+        return {
+            ...carry,
+            ...generatePath(`${path}${childPath}`, childProps, { parentTag: curTag }),
+        };
+    }, result);
+    return paths;
+};
+function getPaths(routes) {
+    const paths = Object.keys(routes);
+    const pathResult = paths.reduce((carry, path) => {
+        const pathProps = routes[path];
+        return {
+            ...carry,
+            ...generatePath(path, pathProps),
+        };
+    }, {});
+    return pathResult;
+}

package/api-docs/schema.d.ts

@@ -0,0 +1 @@
+export default function initSchemas(schemaObj: any): any;

package/api-docs/schema.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = initSchemas;
+const defaultSchema = {
+    type: 'string',
+    example: 'String value here',
+    description: 'Pre-defined string schema',
+};
+const touchObjectProperties = (names) => names.reduce((accu, name) => {
+    if (typeof name === 'string')
+        return {
+            ...accu,
+            [name]: { '$ref': `#/components/schemas/${name}` },
+        };
+    const [schemaName, schemaProps] = name;
+    return {
+        ...accu,
+        [schemaName]: senitizeSchema(schemaProps),
+    };
+}, {});
+const senitizeObjectSchema = (schemaProps) => {
+    const { properties } = schemaProps;
+    const touchedProperties = touchObjectProperties(properties);
+    return { ...schemaProps, properties: touchedProperties };
+};
+const senitizeSchema = (schemaProps) => {
+    const type = schemaProps.type || 'string';
+    if (type !== 'object')
+        return { ...defaultSchema, ...schemaProps };
+    return senitizeObjectSchema(schemaProps);
+};
+function initSchemas(schemaObj) {
+    const schemas = Object.keys(schemaObj);
+    return schemas.reduce((acc, schemaName) => {
+        const schemaProps = schemaObj[schemaName];
+        const schema = senitizeSchema(schemaProps);
+        return ({
+            ...acc,
+            [schemaName]: schema,
+        });
+    }, {});
+}

package/api-docs/security.d.ts

@@ -0,0 +1 @@
+export default function setSecurity(props: any): any;

package/api-docs/security.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = setSecurity;
+const bearer = (bearerAuth = false) => {
+    if (bearerAuth)
+        return {};
+    return {
+        bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+        },
+    };
+};
+const getApiKeys = (apiKeys) => {
+    if (apiKeys.length === 0)
+        return {};
+    return apiKeys.reduce((carry, apiKey) => {
+        const [name, where] = Array.isArray(apiKey)
+            ? apiKey
+            : [apiKey, 'header'];
+        return {
+            ...carry,
+            [name]: {
+                name,
+                type: 'apiKey',
+                in: where,
+            },
+        };
+    }, {});
+};
+function setSecurity(props) {
+    const { bearerAuth = false, apiKeys = [] } = props;
+    const res = {
+        ...bearer(bearerAuth),
+        ...getApiKeys(apiKeys),
+    };
+    const keys = Object.keys(res);
+    if (keys.length === 0)
+        return [{}, {}];
+    const globalSecurities = keys.map((key) => ({
+        [key]: [],
+    }));
+    return [
+        { securitySchemes: res },
+        globalSecurities,
+    ];
+}

package/api-docs/types.d.ts

@@ -0,0 +1,27 @@
+type Info = {
+    version: string;
+    title: string;
+    description: string;
+};
+type ExternalDocs = {
+    description: string;
+    url: string;
+};
+export type Tag = {
+    description: string;
+    externalDocs?: ExternalDocs;
+};
+export type APIKey = Array<string | string[]>;
+export type APIDocs = [any, CallableFunction];
+export type APIDocsOptions = {
+    routes: Record<string, any>;
+    schemas: Record<string, any>;
+};
+export type APIDocsProps = {
+    info: Info;
+    tags?: Record<string, Tag>;
+    bearerAuth?: boolean;
+    apiKeys?: APIKey;
+    paths?: any;
+};
+export {};

package/api-docs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/debug.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Gets the error information for debugin
+ * @param {Error} error - The Error object
+ * @return Object
+ */
+export default function logDebug(error: any): void;

package/debug.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = logDebug;
+/* eslint-disable no-console */
+function getRaiser(error) {
+    const regex = /\((.*):(\d+):(\d+)\)$/;
+    const found = regex.exec(error.stack.split('\n')[2]) || false;
+    if (!found)
+        return {};
+    const [path] = found;
+    const { message } = error;
+    return {
+        path,
+        error: message,
+    };
+}
+/**
+ * Gets the error information for debugin
+ * @param {Error} error - The Error object
+ * @return Object
+ */
+function logDebug(error) {
+    const res = getRaiser(error);
+    const msg = { ...res, source: 'xpressify' };
+    console.log(msg);
+}

package/i18n/index.d.ts

@@ -0,0 +1,9 @@
+type Locale = Record<string, string>;
+type I18n = {
+    locale: Locale;
+    fallbackLang?: string;
+    fallbackLangOnly?: boolean;
+};
+declare const translate: (key: string, replace?: Record<string, any>, pLang?: string) => string;
+export default function initI18n(props: I18n): typeof translate;
+export {};

package/i18n/index.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = initI18n;
+const fs_1 = require("fs");
+const singletonLocale = {};
+let privProps = {
+    fallbackLang: 'en',
+    fallbackLangOnly: false,
+};
+const toLowerCase = (data) => {
+    const entries = Object.entries(data);
+    return entries.reduce((accu, item) => {
+        const [key, value] = item;
+        return { ...accu, [key.toLowerCase()]: value };
+    }, {});
+};
+const loadLocalContent = (locale) => {
+    Object.entries(locale).forEach((localeItem) => {
+        const [localeName, localePath] = localeItem;
+        const data = (0, fs_1.readFileSync)(localePath, 'utf8');
+        const jsonData = JSON.parse(data === '' ? '{}' : data);
+        singletonLocale[localeName] = toLowerCase(jsonData);
+    });
+};
+const localeEscape = (str, obj = {}) => {
+    const keys = Object.keys(obj);
+    return keys.reduce((carry, placeholder) => {
+        const nextResult = carry.replace(`{${placeholder}}`, obj[placeholder]);
+        return nextResult;
+    }, str);
+};
+const getLang = (lang) => {
+    const { fallbackLangOnly, fallbackLang } = privProps;
+    if (fallbackLangOnly)
+        return fallbackLang;
+    return lang;
+};
+const translate = (key, replace = {}, pLang = 'en') => {
+    const lang = getLang(pLang);
+    const { fallbackLang } = privProps;
+    const i18n = singletonLocale[lang] || singletonLocale[fallbackLang] || {};
+    const translation = i18n[key.toLowerCase()] || key;
+    const translated = localeEscape(translation, replace);
+    return translated;
+};
+function initI18n(props) {
+    const { locale, fallbackLang = 'en', fallbackLangOnly = false } = props;
+    privProps = { fallbackLang, fallbackLangOnly };
+    loadLocalContent(locale);
+    return translate;
+}

package/idempotency/index.d.ts

@@ -0,0 +1,7 @@
+export type Idempotency = {
+    ttl?: number;
+    enforced?: boolean;
+    headerKey?: string;
+    validateResponse?: CallableFunction;
+};
+export default function idempotency(props?: Idempotency): (req: any, res: any, next: any) => any;

package/idempotency/index.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = idempotency;
+/* eslint-disable no-console */
+const stream_1 = require("stream");
+const storage_1 = require("./storage");
+const getContentToStore = (response, chunks) => {
+    const { statusCode } = response;
+    const headers = {
+        'content-type': 'application/json',
+        ...response.getHeaders(),
+    };
+    const content = {
+        statusCode,
+        headers,
+        chunks,
+    };
+    return content;
+};
+const parseBody = (chunks) => {
+    const decoded = Buffer.from(chunks.join('')).toString('utf8');
+    try {
+        return JSON.parse(decoded);
+    }
+    catch (error) {
+        const { message } = error;
+        console.error(`[ERROR] API - ${message}`);
+        return {};
+    }
+};
+/**
+ * Validate the rsponse content, by default it validate the HTTP Status Code (200, 201),
+ * but in some case, the response is not only validated by status code, so we can
+ * inject the callback function with maniplucated content as parameter. The callback function
+ * returns boolean value indicate if the response is success or not.
+ */
+const isSuccessResponse = (content, validateResponse = false) => {
+    const { statusCode, chunks } = content;
+    const isSuccess = (statusCode === 200 || statusCode === 201);
+    if (!validateResponse)
+        return isSuccess;
+    const body = parseBody(chunks);
+    return isSuccess && validateResponse({ ...content, body });
+};
+/**
+ * Handles the streaming between middleware
+ * @param {Response} res - ExpressJS HTTP Response object
+ * @param {NextFuction} next - ExpressJS next function
+ * @param {Object} props - Injected properties
+ */
+const handleResponse = (res, next, props = {}) => {
+    const { idempotencyKey, validateResponse } = props;
+    (0, storage_1.create)(idempotencyKey);
+    const [oldWrite, oldEnd] = [res.write, res.end];
+    const chunks = [];
+    res.write = function (chunk) {
+        chunks.push(Buffer.from(chunk));
+        oldWrite.apply(res, arguments);
+    };
+    res.end = function (chunk) {
+        if (chunk)
+            chunks.push(Buffer.from(chunk));
+        const content = getContentToStore(res, chunks);
+        const success = isSuccessResponse(content, validateResponse);
+        if (success)
+            (0, storage_1.store)(idempotencyKey, content);
+        else
+            (0, storage_1.deleteItem)(idempotencyKey);
+        oldEnd.apply(res, arguments);
+    };
+    return next();
+};
+/*
+ * Writes the saved response back to the client, this write only
+ * just the content, but also the previous response headers. This
+ * to make sure the content is written back to the client is exactly
+ * the same as the result.
+ */
+function writeResponse(res, item) {
+    const { chunks, headers, statusCode } = item.response;
+    res.writeHeader(statusCode, {
+        'content-type': 'application/json',
+        'cached-source': 'cache/idempotency',
+        ...headers,
+    });
+    return stream_1.Readable.from(chunks).pipe(res);
+}
+;
+function idempotency(props = {}) {
+    const { headerKey = 'idempotency-key', enforced = false, ttl = (60 * 5), validateResponse = false, } = props;
+    return (req, res, next) => {
+        const { headers, method = 'GET' } = req;
+        if (method.toUpperCase() !== 'POST')
+            return next();
+        const idempotencyKey = headers[headerKey] || false;
+        if (!enforced && !idempotencyKey)
+            return next();
+        if (enforced && !idempotencyKey) {
+            return res.status(422).json({
+                message: 'Idempotency key required for this request',
+                error: true,
+            });
+        }
+        if (!idempotencyKey)
+            return next();
+        if (!(0, storage_1.exists)(idempotencyKey))
+            return handleResponse(res, next, {
+                idempotencyKey,
+                validateResponse,
+            });
+        const item = (0, storage_1.getItem)(idempotencyKey);
+        const { createdAt } = item;
+        const now = new Date();
+        const timelapse = Math.ceil((now.valueOf() - createdAt.valueOf()) / 1000);
+        if (timelapse > ttl) {
+            return res.status(410).json({
+                message: 'Request using this idempotency key has expired.',
+            });
+        }
+        if (item.status === storage_1.status.IN_PROGERSS) {
+            return res.status(202).json({
+                at: new Date(),
+                message: 'Processing',
+            });
+        }
+        if (item.status === storage_1.status.DONE)
+            return writeResponse(res, item);
+        return next();
+    };
+}

package/idempotency/storage.d.ts

@@ -0,0 +1,36 @@
+type Status = 'in-progress' | 'done';
+type Response = {
+    statusCode: number;
+    headers: Record<string, any>;
+    chunks: any;
+};
+type Item = {
+    createdAt: Date;
+    status: Status;
+    referenceNumber?: string | number;
+    response?: Response;
+};
+export declare const status: Record<string, string>;
+export declare const getAll: () => Record<string, Item>;
+export declare const exists: (key: string) => boolean;
+/**
+ * Creates the storage with minimal information (the predetermined default value)
+ * @param {string} key - The key to be added into storage.
+ */
+export declare const create: (key: string) => any;
+/**
+ * Gets the stored item by key
+ * @param {string} key - Storage key
+ * @return object;
+ */
+export declare const getItem: (key: string) => Item | any;
+/**
+ * Stores the response object to be used when passing the stored
+ * result back to the client. This make sure the previouse response
+ * (stored response) is sent back.
+ * @param {string} key - The key of the storage
+ * @param {Response} response - The response information
+ */
+export declare const store: (key: string, response: Response) => void;
+export declare const deleteItem: (key: string) => void;
+export {};