@arsedizioni/ars-utils 22.5.32 → 22.5.34

package/fesm2022/arsedizioni-ars-utils-core.mjs

@@ -71,6 +71,86 @@ class DateInterval {
     }
 }
 
+/**
+ * Conversions between the objects the API speaks (DTOs) and the models a signal form works with.
+ *
+ * The two shapes differ in one systematic way. A DTO leaves out what it does not have: a place
+ * with no phone number simply has no `phone`. A form model cannot afford that — signal forms only
+ * build a child field for a key whose value is defined, and the string validators need a `string`
+ * rather than `string | undefined` — so every editable field is present, holding its empty value
+ * (`''` for text and for the boxes of a datepicker, `false` for a checkbox, `0` for a counter).
+ *
+ * Doing that conversion by hand means a `?? ''` per field on the way in and a `|| undefined` per
+ * field on the way out, twice per form, kept in sync forever. {@link DtoUtils.fromModel} and
+ * {@link DtoUtils.toModel} do it once, driven by a single "empty model" constant that also serves as
+ * the initial value of the form and as what a "clear" button restores.
+ */
+/** The two conversions between an API DTO and the model a signal form works with. */
+class DtoUtils {
+    /**
+     * Builds a form model from the object returned by the API.
+     *
+     * The shape of the result is decided by `empty`, never by the DTO: every key of `empty` is in
+     * the result, taken from the DTO when it carries a usable value and left at its empty value
+     * otherwise. A DTO field that is absent and one that is explicitly `null` are treated the same,
+     * because both mean "the record has no value here" and the form wants its empty value for both.
+     *
+     * Keys that exist only in the model (a multi-select decomposed from a bitmask, a checkbox
+     * extracted from a flags value) simply keep their empty value: fill them in around the call.
+     *
+     * @param empty - The neutral model: it declares every field the form owns, and the value each
+     *                one takes when the DTO does not carry it.
+     * @param dto   - The object coming from the API, or `undefined` when creating a new record.
+     * @returns A new model, never the same reference as `empty` nor as `dto`.
+     * @example
+     * const EMPTY_PLACE: PlaceForm = { name: '', city: '', phone: '', disabled: false };
+     * this.form().reset(DtoUtils.fromModel(EMPTY_PLACE, r.value));
+     */
+    static fromModel(empty, dto) {
+        const model = { ...empty };
+        if (!dto)
+            return model;
+        for (const key of Object.keys(empty)) {
+            const value = dto[key];
+            if (value !== undefined && value !== null) {
+                model[key] = value;
+            }
+        }
+        return model;
+    }
+    /**
+     * Builds the payload for the API from the current form model.
+     *
+     * Every empty value — `''`, `null` or `undefined` — is dropped, so a field the user never filled
+     * in travels as absent instead of reaching the backend as an empty string that would blank the
+     * record. `0` and `false` are NOT empty: an amount of zero and a switch left off are data, and a
+     * filter that wants an unticked box to mean "no filter" has to say so where it builds its query.
+     *
+     * The conversion is shallow: nested objects and arrays are passed through as they are, so a
+     * composite field (a bitmask to rebuild, a nested block to normalize) is handled around the call
+     * — usually by destructuring it out of the model first.
+     *
+     * The return type is {@link Dto}, the model without its empty values, so what the compiler sees
+     * matches what travels: a `coachLevel: CoachLevel | null` field arrives as `CoachLevel` and fits
+     * the optional `coachLevel?: CoachLevel` of the API model. At runtime the empty keys are simply
+     * not there, which is what `HttpClient` serializes anyway.
+     *
+     * @param model - The current form model.
+     * @returns A shallow copy without the empty fields.
+     * @example
+     * this.scmService.places.savePlace(DtoUtils.toModel(this.model()));
+     */
+    static toModel(model) {
+        const dto = {};
+        for (const [key, value] of Object.entries(model)) {
+            if (value === '' || value === null || value === undefined)
+                continue;
+            dto[key] = value;
+        }
+        return dto;
+    }
+}
+
 const UtilsMessages = {
     /**
      * Messages
@@ -2256,5 +2336,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { AutoFocusDirective, BroadcastChannelManager, BroadcastService, CHANNEL_NAME, CopyClipboardDirective, DateFormat, DateInterval, DateIntervalChangeDirective, DeleteModel, EnvironmentService, FileInfo, FormatHtmlPipe, FormatPipe, GroupModel, IDModel, ImportModel, LoginOAuthType, QueryModel, RelationModel, RemoveFocusDirective, ReplacePipe, SafeHtmlPipe, SafeUrlPipe, ScreenService, SearchCallbackPipe, SearchFilterPipe, SelectableModel, SplashService, SystemUtils, ThemeService, UpdateRelationsModel, UtilsMessages, ValueModel };
+export { AutoFocusDirective, BroadcastChannelManager, BroadcastService, CHANNEL_NAME, CopyClipboardDirective, DateFormat, DateInterval, DateIntervalChangeDirective, DeleteModel, DtoUtils, EnvironmentService, FileInfo, FormatHtmlPipe, FormatPipe, GroupModel, IDModel, ImportModel, LoginOAuthType, QueryModel, RelationModel, RemoveFocusDirective, ReplacePipe, SafeHtmlPipe, SafeUrlPipe, ScreenService, SearchCallbackPipe, SearchFilterPipe, SelectableModel, SplashService, SystemUtils, ThemeService, UpdateRelationsModel, UtilsMessages, ValueModel };
 //# sourceMappingURL=arsedizioni-ars-utils-core.mjs.map