@rvoh/dream 0.29.1

package/dist/cjs/src/serializer/decorators/attribute.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Attribute;
+const typechecks_js_1 = require("../../helpers/typechecks.js");
+const dreamAttributeOpenapiShape_js_1 = require("./helpers/dreamAttributeOpenapiShape.js");
+/*
+ * Used to indicate which properties or methods on a
+ * serializer should be returned when rendering this
+ * serializer.
+ *
+ * When calling the @Attribute decorator, the first
+ * argument passed is used to inform psychic of the
+ * intended return shape. The api for the UserSerializer
+ * class is a shorthand hybrid of the openapi spec.
+ *
+ * You are able to pass types directly like so:
+ *
+ * ```ts
+ * class UserSerializer extends DreamSerializer {
+ *   @Attribute('string')
+ *   public email: string
+ * }
+ * ```
+ *
+ * And can also easily communicate array types:
+ *
+ * ```ts
+ * class UserSerializer extends DreamSerializer {
+ *   @Attribute('decimal[]')
+ *   public scores: number[]
+ * }
+ * ```
+ *
+ * For more complex types, utilize the openapi
+ * shorthand api provided by dream to communicate
+ * the custom payload shape:
+ *
+ * ```ts
+ * class UserSerializer extends DreamSerializer {
+ *   @Attribute({
+ *     first: 'string',
+ *     last: {
+ *       type: 'string',
+ *       nullable: true,
+ *     },
+ *   })
+ *   public name: { first: string; last: number | null }
+ * }
+ * ```
+ *
+ * You are able to use advanced openapi types
+ * to communicate complex possibilities:
+ *
+ * ```ts
+ * class UserSerializer extends DreamSerializer {
+ *   @Attribute({
+ *     anyOf: [
+ *       {
+ *         type: 'object',
+ *         properties: {
+ *           first: 'string',
+ *           last: {
+ *             type: 'string',
+ *             nullable: true,
+ *           },
+ *         }
+ *       },
+ *       {
+ *         type: 'string',
+ *         nullable: true,
+ *       },
+ *       {
+ *         $schema: 'UserName'
+ *       }
+ *     ]
+ *   })
+ *   public name: any
+ * }
+ * ```
+ */
+function Attribute(dreamClass_or_shorthandAttribute_or_manualOpenapiOptions, openApiAndRenderOptions_or_renderOptions = {}) {
+    return function (_, context) {
+        const key = context.name;
+        context.addInitializer(function () {
+            const target = this;
+            const serializerClass = target.constructor;
+            if (!serializerClass['globallyInitializingDecorators']) {
+                /**
+                 * Modern Javascript applies implicit accessors to instance properties
+                 * that don't have an accessor explicitly defined in the class definition.
+                 * The instance accessors shadow prototype accessors.
+                 * `addInitializer` is called by Decorators after an instance has been fully
+                 * constructed. We leverage this opportunity to delete the instance accessors
+                 * so that the prototype accessors applied by this decorator can be reached.
+                 */
+                delete this[key];
+                return;
+            }
+            let renderAs;
+            let openApiShape;
+            const { openApiOptions, renderOptions } = openApiAndRenderOptionsToSeparateOptions(openApiAndRenderOptions_or_renderOptions);
+            if (dreamClass_or_shorthandAttribute_or_manualOpenapiOptions?.isDream) {
+                openApiShape = {
+                    ...(0, dreamAttributeOpenapiShape_js_1.dreamAttributeOpenapiShape)(dreamClass_or_shorthandAttribute_or_manualOpenapiOptions, key),
+                    ...openApiOptions,
+                };
+                //
+            }
+            else if ((0, typechecks_js_1.isString)(dreamClass_or_shorthandAttribute_or_manualOpenapiOptions)) {
+                renderAs = dreamClass_or_shorthandAttribute_or_manualOpenapiOptions;
+                openApiShape = { type: renderAs, ...openApiOptions };
+                //
+            }
+            else if (typeof dreamClass_or_shorthandAttribute_or_manualOpenapiOptions === 'object') {
+                openApiShape = dreamClass_or_shorthandAttribute_or_manualOpenapiOptions;
+                renderAs = openApiShape;
+            }
+            else if (dreamClass_or_shorthandAttribute_or_manualOpenapiOptions === undefined) {
+                // no-op
+            }
+            else {
+                throw new Error(`
+Unrecognized first argument to @Attriute decorator: ${JSON.stringify(dreamClass_or_shorthandAttribute_or_manualOpenapiOptions)}
+Serializer: ${serializerClass.name}
+Attribute: ${key}
+`);
+            }
+            serializerClass.attributeStatements = [
+                ...(serializerClass.attributeStatements || []),
+                {
+                    field: key,
+                    functional: context.kind === 'method',
+                    openApiShape,
+                    renderAs,
+                    renderOptions,
+                },
+            ];
+        });
+    };
+}
+function openApiAndRenderOptionsToSeparateOptions(openApiAndRenderOptions) {
+    let openApiOptions;
+    let renderOptions;
+    if (openApiAndRenderOptions.description !== undefined) {
+        openApiOptions ||= {};
+        openApiOptions.description = openApiAndRenderOptions.description;
+    }
+    if (openApiAndRenderOptions.nullable !== undefined) {
+        openApiOptions ||= {};
+        openApiOptions.nullable = openApiAndRenderOptions.nullable;
+    }
+    if (openApiAndRenderOptions.delegate !== undefined) {
+        renderOptions ||= {};
+        renderOptions.delegate = openApiAndRenderOptions.delegate;
+    }
+    if (openApiAndRenderOptions.precision !== undefined) {
+        renderOptions ||= {};
+        renderOptions.precision = openApiAndRenderOptions.precision;
+    }
+    return { openApiOptions, renderOptions };
+}

package/dist/cjs/src/serializer/decorators/helpers/dreamAttributeOpenapiShape.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseCustomOpenapiForJson = void 0;
+exports.dreamAttributeOpenapiShape = dreamAttributeOpenapiShape;
+function dreamAttributeOpenapiShape(dreamClass, column) {
+    const dream = dreamClass.prototype;
+    const dreamColumnInfo = dream.schema[dream.table]?.columns[column];
+    if (!dreamColumnInfo)
+        return { type: 'string' };
+    const singleType = singularAttributeOpenapiShape(dreamColumnInfo);
+    const nullable = dreamColumnInfo.allowNull ? { nullable: true } : {};
+    if (dreamColumnInfo.isArray)
+        return { type: 'array', items: singleType, ...nullable };
+    return {
+        ...singleType,
+        ...nullable,
+    };
+}
+function singularAttributeOpenapiShape(dreamColumnInfo) {
+    if (dreamColumnInfo.enumValues)
+        return {
+            type: 'string',
+            enum: [...dreamColumnInfo.enumValues, ...(dreamColumnInfo.allowNull ? ['null'] : [])],
+        };
+    switch (dreamColumnInfo.dbType.replace('[]', '')) {
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'bigint':
+        case 'bigserial':
+        case 'bytea':
+        case 'char':
+        case 'character varying':
+        case 'character':
+        case 'cidr':
+        case 'citext':
+        case 'inet':
+        case 'macaddr':
+        case 'money':
+        case 'path':
+        case 'text':
+        case 'uuid':
+        case 'varbit':
+        case 'varchar':
+        case 'xml':
+            return { type: 'string' };
+        case 'integer':
+        case 'serial':
+        case 'smallint':
+        case 'smallserial':
+            return { type: 'integer' };
+        case 'decimal':
+        case 'numeric':
+            return { type: 'number', format: 'decimal' };
+        case 'double':
+        case 'real':
+            return { type: 'number' };
+        case 'datetime':
+        case 'time':
+        case 'time with time zone':
+        case 'timestamp':
+        case 'timestamp with time zone':
+        case 'timestamp without time zone':
+            return { type: 'string', format: 'date-time' };
+        case 'date':
+            return { type: 'string', format: 'date' };
+        case 'json':
+        case 'jsonb':
+            throw new UseCustomOpenapiForJson();
+        default:
+            throw new Error(`Unrecognized dbType used in serializer OpenAPI type declaration: ${dreamColumnInfo.dbType}`);
+    }
+}
+class UseCustomOpenapiForJson extends Error {
+    get message() {
+        return `Use custom OpenAPI declaration (OpenapiSchemaBodyShorthand) to define shape of json and jsonb fields`;
+    }
+}
+exports.UseCustomOpenapiForJson = UseCustomOpenapiForJson;

package/dist/cjs/src/serializer/decorators/helpers/hasSerializersGetter.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+function default_1(dreamOrSerializerClass) {
+    try {
+        return !!dreamOrSerializerClass?.prototype?.serializers;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cjs/src/serializer/decorators/helpers/maybeSerializableToDreamSerializerCallbackFunction.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const hasSerializersGetter_js_1 = require("./hasSerializersGetter.js");
+function default_1(dreamOrSerializerClass) {
+    if (dreamOrSerializerClass === null)
+        return null;
+    if (Array.isArray(dreamOrSerializerClass))
+        return null;
+    if (dreamOrSerializerClass.isDream)
+        return null;
+    if ((0, hasSerializersGetter_js_1.default)(dreamOrSerializerClass))
+        return null;
+    // this must not call the function because this function is called as part of decorator
+    // execution, which happens at file load time and creates circular dependencies if the
+    // class is referenced directly during file load
+    if (dreamOrSerializerClass instanceof Function)
+        return dreamOrSerializerClass;
+    return null;
+}

package/dist/cjs/src/serializer/index.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const luxon_1 = require("luxon");
+const index_js_1 = require("../dream-application/index.js");
+const types_js_1 = require("../dream/types.js");
+const GlobalNameNotSet_js_1 = require("../errors/dream-application/GlobalNameNotSet.js");
+const MissingSerializersDefinition_js_1 = require("../errors/MissingSerializersDefinition.js");
+const FailedToRenderThroughAssociationForSerializer_js_1 = require("../errors/serializers/FailedToRenderThroughAssociationForSerializer.js");
+const camelize_js_1 = require("../helpers/camelize.js");
+const compact_js_1 = require("../helpers/compact.js");
+const inferSerializerFromDreamOrViewModel_js_1 = require("../helpers/inferSerializerFromDreamOrViewModel.js");
+const round_js_1 = require("../helpers/round.js");
+const snakeify_js_1 = require("../helpers/snakeify.js");
+const maybeSerializableToDreamSerializerCallbackFunction_js_1 = require("./decorators/helpers/maybeSerializableToDreamSerializerCallbackFunction.js");
+class DreamSerializer {
+    static attributeStatements = [];
+    static associationStatements = [];
+    static isDreamSerializer = true;
+    static _globalName;
+    /**
+     * @internal
+     *
+     * Certain features (e.g. building OpenAPI specs from Attribute and RendersOne/Many decorators)
+     * need static access to things set up by decorators. Stage 3 Decorators change the context that is available
+     * at decoration time such that the class of a property being decorated is only avilable during instance instantiation. In order
+     * to only apply static values once, on boot, `globallyInitializingDecorators` is set to true on DreamSerializer, and all serializers are instantiated.
+     *
+     */
+    static globallyInitializingDecorators = false;
+    static get globalName() {
+        if (!this._globalName)
+            throw new GlobalNameNotSet_js_1.default(this);
+        return this._globalName;
+    }
+    static setGlobalName(globalName) {
+        this._globalName = globalName;
+    }
+    static get openapiName() {
+        // TODO: make this customizable by the user
+        const pathDelimiter = '_';
+        return this.name.replace(/Serializer$/, '').replace(/\//g, pathDelimiter);
+    }
+    static render(data, opts = {}) {
+        return new this(data).passthrough(opts.passthrough).render();
+    }
+    static renderArray(dataArr, opts = {}) {
+        return dataArr.map(data => this.render(data, opts));
+    }
+    static getAssociatedSerializersForOpenapi(associationStatement) {
+        const serializer = (0, maybeSerializableToDreamSerializerCallbackFunction_js_1.default)(associationStatement.dreamOrSerializerClass);
+        if (serializer)
+            return [serializer()];
+        let classOrClasses = associationStatement.dreamOrSerializerClass;
+        if (!classOrClasses)
+            return null;
+        if (!Array.isArray(classOrClasses)) {
+            classOrClasses = [classOrClasses];
+        }
+        return (0, compact_js_1.default)(classOrClasses.map(klass => (0, inferSerializerFromDreamOrViewModel_js_1.inferSerializerFromDreamClassOrViewModelClass)(klass, associationStatement.serializerKey)));
+    }
+    static getAssociatedSerializerDuringRender(associatedData, associationStatement) {
+        const dreamSerializerCallbackFunctionOrNull = (0, maybeSerializableToDreamSerializerCallbackFunction_js_1.default)(associationStatement.dreamOrSerializerClass);
+        if (dreamSerializerCallbackFunctionOrNull)
+            return dreamSerializerCallbackFunctionOrNull();
+        return (0, inferSerializerFromDreamOrViewModel_js_1.default)(associatedData, associationStatement.serializerKey);
+    }
+    _data;
+    _casing = null;
+    isDreamSerializerInstance = true;
+    constructor(data) {
+        this._data = data;
+        const serializerPrototype = Object.getPrototypeOf(this);
+        const attributeStatements = [...this.constructor.attributeStatements];
+        attributeStatements.forEach(attributeStatement => {
+            if (!attributeStatement.functional) {
+                if (!Object.getOwnPropertyDescriptor(serializerPrototype, attributeStatement.field)?.get) {
+                    Object.defineProperty(serializerPrototype, attributeStatement.field, {
+                        get() {
+                            return this.$data[attributeStatement.field];
+                        },
+                        set(val) {
+                            this.$data[attributeStatement.field] = val;
+                        },
+                    });
+                }
+            }
+        });
+    }
+    get $data() {
+        return this._data;
+    }
+    get attributes() {
+        const attributes = [...this.constructor.attributeStatements.map(s => s.field)];
+        switch (this._casing) {
+            case 'camel':
+                return attributes.map(attr => (0, camelize_js_1.default)(attr));
+            case 'snake':
+                return attributes.map(attr => (0, snakeify_js_1.default)(attr));
+            default:
+                return attributes;
+        }
+    }
+    casing(casing) {
+        this._casing = casing;
+        return this;
+    }
+    $passthroughData = {};
+    passthrough(obj) {
+        this.$passthroughData = {
+            ...this.$passthroughData,
+            ...obj,
+        };
+        return this;
+    }
+    absorbPassthrough(serializer) {
+        this.passthrough(serializer.$passthroughData);
+        return this;
+    }
+    render() {
+        if (!this._casing) {
+            const dreamApp = index_js_1.default.getOrFail();
+            this._casing = dreamApp.serializerCasing || 'camel';
+        }
+        return this.renderOne();
+    }
+    renderOne() {
+        let returnObj = {};
+        for (const associationStatement of this.constructor.associationStatements) {
+            if (associationStatement.flatten) {
+                returnObj = {
+                    ...returnObj,
+                    ...this.applyAssociation(associationStatement),
+                };
+            }
+            else {
+                returnObj[this.applyCasingToField(associationStatement.field)] =
+                    this.applyAssociation(associationStatement);
+            }
+        }
+        this.attributes.forEach(attr => {
+            const attributeStatement = this.constructor.attributeStatements.find(s => [attr, this.applyCasingToField(attr)].includes(s.field) ||
+                [attr, this.applyCasingToField(attr)].includes(this.applyCasingToField(s.field)));
+            if (attributeStatement) {
+                const { field, renderAs, renderOptions } = attributeStatement;
+                const fieldWithCasing = this.applyCasingToField(field);
+                let dateValue;
+                let decimalValue;
+                switch (this.computedRenderAs(renderAs)) {
+                    case 'date':
+                        dateValue = this.getAttributeValue(attributeStatement);
+                        returnObj[fieldWithCasing] = dateValue?.toISODate() || null;
+                        break;
+                    case 'date-time':
+                        dateValue = this.getAttributeValue(attributeStatement);
+                        returnObj[fieldWithCasing] = dateValue?.toISO()
+                            ? luxon_1.DateTime.fromISO(dateValue.toISO()).toISO()
+                            : null;
+                        break;
+                    case 'decimal':
+                        decimalValue = this.numberOrStringToNumber(this.getAttributeValue(attributeStatement));
+                        returnObj[fieldWithCasing] =
+                            decimalValue === null
+                                ? null
+                                : renderOptions?.precision === undefined
+                                    ? decimalValue
+                                    : (0, round_js_1.default)(decimalValue, renderOptions?.precision);
+                        break;
+                    case 'integer':
+                        decimalValue = this.numberOrStringToNumber(this.getAttributeValue(attributeStatement));
+                        returnObj[fieldWithCasing] = decimalValue === null ? null : (0, round_js_1.default)(decimalValue);
+                        break;
+                    default:
+                        returnObj[fieldWithCasing] = this.getAttributeValue(attributeStatement);
+                }
+            }
+        });
+        return returnObj;
+    }
+    numberOrStringToNumber(num) {
+        if (num === undefined)
+            return null;
+        if (num === null)
+            return null;
+        if (typeof num === 'number')
+            return num;
+        return Number(num);
+    }
+    computedRenderAs(renderAs) {
+        if (typeof renderAs === 'object') {
+            const safeRenderAs = renderAs;
+            if (safeRenderAs.type === 'string' || safeRenderAs.type === 'number') {
+                if (safeRenderAs.format)
+                    return safeRenderAs.format;
+                return safeRenderAs.type;
+            }
+            if (safeRenderAs.type)
+                return safeRenderAs.type;
+        }
+        return renderAs;
+    }
+    applyAssociation(associationStatement) {
+        const associatedData = this.associatedData(associationStatement);
+        if (associationStatement.type === 'RendersMany' && Array.isArray(associatedData))
+            return associatedData.map(d => this.renderAssociation(d, associationStatement));
+        else if (associatedData)
+            return this.renderAssociation(associatedData, associationStatement);
+        return associationStatement.type === 'RendersMany' ? [] : null;
+    }
+    renderAssociation(associatedData, associationStatement) {
+        const SerializerClass = DreamSerializer.getAssociatedSerializerDuringRender(associatedData, associationStatement);
+        if (!SerializerClass)
+            throw new MissingSerializersDefinition_js_1.default(associatedData.constructor);
+        return new SerializerClass(associatedData).absorbPassthrough(this).render();
+    }
+    associatedData(associationStatement) {
+        const delegateToPassthroughData = associationStatement.source === types_js_1.DreamConst.passthrough;
+        let self = (delegateToPassthroughData ? this.$passthroughData : this.$data);
+        if (associationStatement.through) {
+            const throughField = associationStatement.through;
+            if (Array.isArray(self)) {
+                self = self.flatMap(singleField => singleField[throughField]);
+            }
+            else {
+                self = self[throughField];
+            }
+            if (self === undefined) {
+                throw new FailedToRenderThroughAssociationForSerializer_js_1.default(this.constructor.name, throughField);
+            }
+        }
+        if (Array.isArray(self)) {
+            return self.flatMap(item => {
+                let returnValue;
+                if (delegateToPassthroughData)
+                    returnValue = item[associationStatement.field];
+                returnValue = item[associationStatement.source];
+                return Array.isArray(returnValue) ? returnValue.flat() : returnValue;
+            });
+        }
+        else {
+            if (delegateToPassthroughData)
+                return self[associationStatement.field];
+            return self[associationStatement.source];
+        }
+    }
+    getAttributeValue(attributeStatement) {
+        const { field } = attributeStatement;
+        let pathToValue = this;
+        if (attributeStatement.renderOptions?.delegate) {
+            const delegateField = attributeStatement.renderOptions?.delegate;
+            pathToValue = this.$data?.[delegateField] || null;
+        }
+        const valueOrCb = pathToValue[field];
+        if (attributeStatement.functional) {
+            return valueOrCb.call(this, this.$data);
+        }
+        else {
+            return valueOrCb;
+        }
+    }
+    applyCasingToField(field) {
+        switch (this._casing) {
+            case 'camel':
+                return (0, camelize_js_1.default)(field);
+            case 'snake':
+                return (0, snakeify_js_1.default)(field);
+            default:
+                return field;
+        }
+    }
+}
+exports.default = DreamSerializer;

package/dist/esm/boilerplate/package.json

@@ -0,0 +1,42 @@
+{
+    "type": "module",
+    "name": "tbd",
+    "version": "0.0.0",
+    "main": "src/index.ts",
+    "author": "tbd",
+    "private": true,
+    "scripts": {
+        "dream": "yarn dreamts",
+        "dreamjs": "node  --experimental-modules dist/test-app/cli/index.js",
+        "dreamts": "node --experimental-specifier-resolution=node --import=./bin/esm.js ./src/cli/index.ts",
+        "console": "node --experimental-specifier-resolution=node --import=./bin/esm.js ./src/conf/repl.ts",
+        "lint": "yarn run eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\""
+    },
+    "dependencies": {
+        "@rvohealth/dream": "1.0.0",
+        "@types/luxon": "^3.4.2",
+        "@types/node": "^20.11.17",
+        "@types/pg": "^8.11.3",
+        "kysely-codegen": "^0.11.0",
+        "kysely": "^0.27.2",
+        "luxon": "^3.4.4",
+        "pg": "^8.11.3",
+        "winston": "^3.13.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "=9.0.0",
+        "@rvohealth/dream-spec-helpers": "1.0.0",
+        "@types/jest": "^29.5.12",
+        "@types/luxon": "^3.4.2",
+        "@types/node": "^20.11.17",
+        "@types/pg": "^8.11.3",
+        "eslint": "=9.0.0",
+        "jest": "^29.7.0",
+        "luxon-jest-matchers": "^0.1.14",
+        "prettier": "^3.2.5",
+        "ts-jest": "^29.1.4",
+        "ts-node": "^10.9.2",
+        "typescript-eslint": "=7.18.0",
+        "typescript": "^5.4.5"
+    }
+}