{"_id":"@alkemist/ngx-form-supervisor","name":"@alkemist/ngx-form-supervisor","dist-tags":{"latest":"1.1.16"},"versions":{"1.1.16":{"name":"@alkemist/ngx-form-supervisor","version":"1.1.16","description":"Ngx Form Supervisor","repository":{"type":"git","url":"git+https://github.com/alkemist/ng-libraries.git"},"publishConfig":{"registry":"https://registry.npmjs.org/"},"engines":{"node":">=16.0.0"},"keywords":["typescript","angular","smart","form","restore","comparison","diff","difference","change"],"author":{"name":"Jaden ACHAIN"},"license":"Apache-2.0","homepage":"https://github.com/alkemist/ng-libraries/tree/main/projects/ngx-form-supervisor#readme","bugs":{"url":"https://github.com/alkemist/ng-libraries/issues"},"peerDependencies":{"@alkemist/compare-engine":"^1.3.4","@alkemist/smart-tools":"^1.1.15","@angular/common":"^17.3.0","@angular/core":"^17.3.0"},"dependencies":{"tslib":"^2.3.0"},"private":false,"sideEffects":false,"module":"fesm2022/alkemist-ngx-form-supervisor.mjs","typings":"index.d.ts","exports":{"./package.json":{"default":"./package.json"},".":{"types":"./index.d.ts","esm2022":"./esm2022/alkemist-ngx-form-supervisor.mjs","esm":"./esm2022/alkemist-ngx-form-supervisor.mjs","default":"./fesm2022/alkemist-ngx-form-supervisor.mjs"}},"_id":"@alkemist/ngx-form-supervisor@1.1.16","gitHead":"250647fbb38cad7ca6a2f585ef075848d68ba93f","_nodeVersion":"20.11.1","_npmVersion":"10.5.0","dist":{"integrity":"sha512-f740cJTVilrmsI6zWHdgqtiI5dnQyEaMvH240MPFAdlwtzUsRVtS1yrQtIupykMAGWYkkB486QdFKuebz3wCxw==","shasum":"0b6cbb80283eeb870ddf1f5532d45551aedd3a6d","tarball":"https://registry.npmjs.org/@alkemist/ngx-form-supervisor/-/ngx-form-supervisor-1.1.16.tgz","fileCount":22,"unpackedSize":209503,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDNmFoqN99w//5SHUTlbXBncSzftrmy0kExNtLj9Md1oQIgfEQ38c4x5uqeWcpAR0mLTAI5tDfsyDjVqZzfX6zFUNE="}]},"_npmUser":{"name":"alkemist","email":"achain.jeremy@gmail.com"},"directories":{},"maintainers":[{"name":"alkemist","email":"achain.jeremy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ngx-form-supervisor_1.1.16_1712228100977_0.33316198168206257"},"_hasShrinkwrap":false}},"time":{"created":"2024-04-04T10:55:00.864Z","1.1.16":"2024-04-04T10:55:01.173Z","modified":"2024-04-04T10:55:01.492Z"},"maintainers":[{"name":"alkemist","email":"achain.jeremy@gmail.com"}],"description":"Ngx Form Supervisor","homepage":"https://github.com/alkemist/ng-libraries/tree/main/projects/ngx-form-supervisor#readme","keywords":["typescript","angular","smart","form","restore","comparison","diff","difference","change"],"repository":{"type":"git","url":"git+https://github.com/alkemist/ng-libraries.git"},"author":{"name":"Jaden ACHAIN"},"bugs":{"url":"https://github.com/alkemist/ng-libraries/issues"},"license":"Apache-2.0","readme":"# Form Supervisor\n\n## Installation\n\n* From npm: `npm install @alkemist/ng-form-supervisor`\n* From yarn: `yarn add @alkemist/ng-form-supervisor`\n\n## Test\n\n* From npm: `npm test`\n* From yarn: `yarn test`\n\n## About\n\nAdds new functionality to Angular forms (FormGroup, FormArray, FormControl):\n\n- A modification state between initial value and form value, using comparison\n  engine ([@alkemist/compare-engine](https://github.com/alkemist/compare-engine))\n- The ability to restore to original value, but also to modify initial value\n- Even if you decide not to emit an event (emitEvent : false), parents and children are warned of the value change\n- The ability to add an element to a FormArray only with a value, the only constraint being that when the FormArray is\n  initialized, it must contain at least one element, to determine its \"construction signature\" (the type of element it\n  contains, see example)  \n  The configuration is saved (in case the array is emptied) and passed on to the children.\n\nSupervisors will recursively build the supervisors of the form's child elements (see example).\n\n## Examples\n\n    import {FormGroupSupervisor} from '@alkemist/ng-form-supervisor';\n\n    type USER_GROUP = \"USER\" | \"ADMIN\" | \"SUPERADMIN\";\n\n    interface ComplexeUser extends BasicUser {\n        groups: USER_GROUP[],\n        profiles: {\n            username: string,\n            avatar: string | null,\n            badges: string[],\n        }[]\n        rights: {\n            viewProfile: boolean,\n            viewUsers: boolean\n        }\n    }\n\n    const formGroup =\n        new FormGroup({\n            id: new FormControl<number | null>(\"id\"),\n            name: new FormControl<string | null>(\"name\", [\n                Validators.required,\n                Validators.minLength(3),\n            ]),\n            groups: new FormArray([\n                new FormControl<USER_GROUP>(\"USER\")\n            ], [Validators.required]),\n\n            profiles: new FormArray([\n                new FormGroup({\n                    username: new FormControl<string>(\"username\"),\n                    avatar: new FormControl<string | null>(null),\n                    badges: new FormArray([\n                        new FormControl<string | null>(\"badge\")\n                    ]),\n                })\n            ], [Validators.required]),\n\n            rights: new FormGroup({\n                viewProfile: new FormControl<boolean | null>(true),\n                viewUsers: new FormControl<boolean | null>(false),\n            }),\n        });\n\n\n    // The \"group.value\" parameter permits \"form self-determination\"\n    const supervisor =\n            new FormGroupSupervisor(group, group.value as ComplexeUser);\n\n    // Each child of the form has its own supervisor\n    // who manages its state of comparison between the initial value and the value of the form.\n\n    supervisor.get(\"name\")                                // return a FormControlSupervisor\n    supervisor.get(\"groups\")                              // return a FormArrayControlSupervisor\n    supervisor.get(\"groups\").at(0)                        // return a FormControlSupervisor\n    supervisor.get(\"profiles\")                            // return a FormArrayGroupSupervisor\n    supervisor.get(\"profiles\").at(0)                      // return a FormGroupSupervisor\n    supervisor.get(\"profiles\").at(0).get('username')      // return a FormControlSupervisor\n    supervisor.get(\"profiles\").at(0).get('badges')        // return a FormArrayControlSupervisor\n    supervisor.get(\"profiles\").at(0).get('badges').at(0)  // return a FormControlSupervisor\n    supervisor.get(\"rights\")                              // return a FormGroupSupervisor\n    supervisor.get(\"rights\").get(\"viewProfile\")           // return a FormControlSupervisor\n\n    # For add a array item\n    supervisor.get(\"profiles\").push({username: \"\", avatar: null, badges: []})\n\n    # instead of\n    (formGroup.get(\"profiles\") as FormArray).push(new FormGroup({\n            username: new FormControl<string>(\"\", [Validators.required]),\n            avatar: new FormControl<string | null>(null),\n            badges: new FormArray([]),\n        }));\n\n    # State can be recovered in this way:\n    supervisor.hasChange()                                // return true\n    supervisor.get(\"profiles\").hasChange()                // return true\n    supervisor.get(\"profiles\").at(0).hasChange()          // return false\n    supervisor.get(\"profiles\").at(1).hasChange()          // return false\n    supervisor.get(\"rights\").hasChange()                  // return false\n\n    supervisor.getChanges()                               \n    /* return \n        {\n            id:         CompareState.EQUAL,\n            name:       CompareState.EQUAL,\n            groups:     CompareState.EQUAL,\n            profiles:   CompareState.UPDATED,\n            rights:     CompareState.EQUAL\n        }\n    */\n\n    supervisor.get(\"profiles\").getChanges()                               \n    /* return \n        [\n          CompareState.EQUAL,\n          CompareState.ADDED,\n        ]\n    */\n\n    supervisor.get(\"profiles\").setValue([])\n    supervisor.get(\"profiles\").getInitialChanges(0)    // return CompareState.REMOVED\n\n    supervisor.resetInitialValue()                                \n    supervisor.hasChange()                             // return false\n\n## Exposed models, enums and utils\n\n    abstract class FormSupervisor<\n        DATA_TYPE = any,\n        FORM_TYPE extends AbstractControl = AbstractControl\n    > {\n        get form(): FORM_TYPE\n    \n        get valid(): boolean\n    \n        get value(): FormDataType<DATA_TYPE, FORM_TYPE> | undefined\n    \n        get valueChanges(): Observable<FormDataType<DATA_TYPE, FORM_TYPE>>\n    \n        setValue(value: FormRawDataType<DATA_TYPE, FORM_TYPE> | undefined, options?: FormOptions): void\n        \n        getChanges(path: ValueKey | ValueKey[] = ''): CompareState | GenericValueRecord<FormChange> | FormChange[]\n\n        getInitialChanges(path: ValueKey | ValueKey[] = ''): CompareState | GenericValueRecord<FormChange> | FormChange[]\n\n        reset(options?: FormOptions): void\n\n        updateInitialValue(value?: FormRawDataType<DATA_TYPE, FORM_TYPE>)\n\n        resetInitialValue(): void\n\n        hasChange(): boolean\n\n        restore(options?: FormOptions)\n    }\n\n    class FormGroupSupervisor<\n        DATA_TYPE,\n        FORM_GROUP_TYPE extends FormGroup,\n    >\n        extends FormSupervisor<\n            DATA_TYPE,\n            FORM_GROUP_TYPE\n        > {\n            constructor(\n                group: FORM_GROUP_TYPE,\n                data: DATA_TYPE,\n                determineArrayIndexFn: ((paths: ValueKey[]) => ValueKey) | undefined = undefined,\n            )\n    }\n\n    abstract class FormArraySupervisor<\n        DATA_TYPE,\n        FORM_TYPE extends FormArray,\n        SUPERVISOR_TYPE extends FormSupervisor<DATA_TYPE> =\n            GetFormArrayGenericClass<FORM_TYPE> extends FormGroup\n                ? FormGroupSupervisor<DATA_TYPE, GetFormArrayGenericClass<FORM_TYPE>>\n                : FormControlSupervisor<DATA_TYPE>,\n    > \n        extends FormSupervisor<\n            DATA_TYPE[],\n            FORM_TYPE\n        > {\n            patchValue(value: DATA_TYPE[], options?: FormOptions)\n\n            clear(options?: FormOptions)\n\n            at(index: number): SUPERVISOR_TYPE\n\n            push(itemValue: DATA_TYPE, options?: FormOptions)\n\n            insert(itemValue: DATA_TYPE, index: number, options?: FormOptions)\n\n            remove(index: number)\n\n            splice(start: number, deleteCount?: number)\n    }\n\n    class FormArrayControlSupervisor<DATA_TYPE> \n        extends FormArraySupervisor<\n            DATA_TYPE,\n            FormArray<FormControl<DATA_TYPE | null>>\n        > {\n            constructor(\n                items: FormArray<FormControl<DATA_TYPE | null>>,\n                determineArrayIndexFn: ((paths: ValueKey[]) => ValueKey) | undefined = undefined,\n            )\n    }\n\n\n    class FormArrayGroupSupervisor<DATA_TYPE, FORM_TYPE extends FormArray> \n        extends FormArraySupervisor<\n            DATA_TYPE,\n            FormArray<FormControl<DATA_TYPE | null>>\n        > {\n            constructor(\n                items: FORM_TYPE,\n                values: DATA_TYPE[],\n                determineArrayIndexFn: ((paths: ValueKey[]) => ValueKey) | undefined = undefined,\n            )\n    }\n\n    export class FormGroupSupervisor<\n        DATA_TYPE,\n        FORM_GROUP_TYPE extends FormGroup,\n    >\n        extends FormSupervisor<\n            DATA_TYPE,\n            FORM_GROUP_TYPE\n        > {\n            constructor(\n                protected group: FORM_GROUP_TYPE,\n                data: DATA_TYPE,\n                determineArrayIndexFn: ((paths: ValueKey[]) => ValueKey) | undefined = undefined,\n            )\n\n            patchValue(value: PartialGroupValueType<GetFormGroupGenericClass<FORM_GROUP_TYPE, DATA_TYPE>, DATA_TYPE>, options?: FormOptions)\n\n            clear(options?: FormOptions)\n\n            get<K extends keyof DATA_TYPE>(property: K)\n                : SupervisorType<DATA_TYPE[K], GetFormGroupGenericClass<FORM_GROUP_TYPE, DATA_TYPE>[K]>\n        \n            getFormProperty<K extends keyof DATA_TYPE>(property: K)\n                : GetFormGroupGenericClass<FORM_GROUP_TYPE, DATA_TYPE>[K]\n    }\n\n## License\n\n[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)\n","readmeFilename":"README.md"}