{"id":19176900,"url":"https://github.com/oasisdigital/angular-typed-forms-helpers","last_synced_at":"2025-05-07T19:42:15.148Z","repository":{"id":50732260,"uuid":"501403952","full_name":"OasisDigital/angular-typed-forms-helpers","owner":"OasisDigital","description":"Some helper types for when you are dealing with Angular's typed reactive forms system","archived":false,"fork":false,"pushed_at":"2025-02-20T18:42:33.000Z","size":59,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-04T07:03:35.396Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OasisDigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-08T20:39:46.000Z","updated_at":"2025-02-20T18:42:37.000Z","dependencies_parsed_at":"2024-07-18T16:18:54.296Z","dependency_job_id":null,"html_url":"https://github.com/OasisDigital/angular-typed-forms-helpers","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"c74d1420e15f7333d3e982963e7ede1f1656f909"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OasisDigital%2Fangular-typed-forms-helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OasisDigital%2Fangular-typed-forms-helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OasisDigital%2Fangular-typed-forms-helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OasisDigital%2Fangular-typed-forms-helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OasisDigital","download_url":"https://codeload.github.com/OasisDigital/angular-typed-forms-helpers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252945803,"owners_count":21829661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T10:31:01.488Z","updated_at":"2025-05-07T19:42:15.123Z","avatar_url":"https://github.com/OasisDigital.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Angular Typed Forms Helpers\n\nThis package includes helper types for when you are dealing with Angular's typed reactive forms\nsystem. These types allow for translating raw typescript interfaces/types into the Reactive Forms\nTypes and back into raw typescript interfaces/types for the value.\n\n## Installation\n\n### npm\n\n`npm install --save-dev @oasisdigital/angular-typed-forms-helpers`\n\n### yarn\n\n`yarn add --dev @oasisdigital/angular-typed-forms-helpers`\n\nThen you can simply import the helper interfaces from `angular-typed-forms-helpers`.\n\n### Version Compatibility with `@angular/forms`\n\n- 3.4.x - Angular 19.x.x\n- 3.3.x - Angular 18.x.x\n- 3.2.x - Angular 17.x.x\n- 3.1.x - Angular 16.x.x\n- 2.2.x - Angular 15.x.x\n- 2.1.x - Angular 14.x.x\n\n## [Stackblitz Demo](https://stackblitz.com/edit/angular-typed-forms-helpers-demo?file=src%2Fapp%2Fapp.component.ts)\n\n\u003e For the below sections describing the different interfaces/types, if you want a `NonNullable`\n\u003e version of any of them simply prefix the type/interface with `NonNullable`. This does not include\n\u003e the value \u0026 rawValue types as they work regardless of Nullability.\n\u003e\n\u003e For example, with `AngularForm` you would do `NonNullableAngularForm`.\n\n## `AngularForm` Interface\n\nThis interface allows for _deeply_ translating an object or general TS type/interface into one of\nthe 3 main Angular Reactive Forms types (FormControl, FormGroup, FormArray).\n\n```ts\nimport { FormArray, FormControl, FormGroup } from '@angular/forms';\nimport { AngularForm } from '@oasisdigital/angular-typed-forms-helpers';\n\nexport interface Animal {\n  name: string;\n  species: string;\n  lifeStage: string;\n  birthDate: Date;\n  alive: boolean;\n}\n\nexport interface Zone {\n  name: string;\n  maxCapacity: number;\n  animals: Animal[];\n}\n\ntype AnimalForm = AngularForm\u003cAnimal\u003e;\ntype ZoneForm = AngularForm\u003cZone\u003e;\n\nconst animalForm: AnimalForm = new FormGroup({\n  name: new FormControl(''),\n  species: new FormControl(''),\n  lifeStage: new FormControl(''),\n  birthDate: new FormControl(new Date('01 Jan 1994')),\n  alive: new FormControl(true),\n});\n\nconst zoneForm: ZoneForm = new FormGroup({\n  name: new FormControl(''),\n  maxCapacity: new FormControl(10),\n  animals: new FormArray\u003cAnimalForm\u003e([]),\n});\n```\n\nIt is important to note this interface only covers basic cases of form structures, it makes the\nassumption that all objects are FormGroups and arrays are FormArrays. If you would like to convert\non a per property basis consider using the `AngularFormGroup` or `AngularFormArray` from the below\nsections.\n\n\u003e The `NonNullable` version of this type is `NonNullableAngularForm`.\n\n## `AngularFormGroupShallow` Interface\n\nThis interface will do a _shallow_ conversion of an object over to the Angular Typed Forms system.\nWhere every property of the object becomes a FormControl.\n\n```ts\ntype ZoneForm = AngularFormGroupShallow\u003cZone\u003e;\nconst zoneForm: ZoneForm = new FormGroup({\n  name: new FormControl(''),\n  maxCapacity: new FormControl(10),\n  animals: new FormControl\u003cAnimal[]\u003e([]),\n});\n```\n\n\u003e The `NonNullable` version of this type is `NonNullableAngularFormGroupShallow`.\n\n## `AngularFormGroup` Interface\n\nThis is a subset of the `AngularForm` interface that deeply converts an object over to the Angular\nTyped Forms system. If you give an array type to this interface the return will be `never`. This is\ndue to a limitation of diffing arrays and objects in the generic extension type.\n\n```ts\ntype ZoneForm = AngularFormGroup\u003cZone\u003e;\nconst zoneForm: ZoneForm = new FormGroup({\n  name: new FormControl(''),\n  maxCapacity: new FormControl(10),\n  animals: new FormArray\u003cAnimalForm[]\u003e([]),\n});\n```\n\n\u003e The `NonNullable` version of this type is `NonNullableAngularFormGroup`.\n\n## `AngularFormArrayShallow` Interface\n\nThis interface will do a _shallow_ conversion of an array over to the Angular Typed Forms system.\nWhere the Array subtype becomes a matching FormControl subtype for the FormArray.\n\n```ts\ntype ZonesForm = AngularFormArrayShallow\u003cZone[]\u003e;\nconst zonesForm: ZonesForm = new FormArray([\n  {\n    name: new FormControl(''),\n    maxCapacity: new FormControl(10),\n    animals: new FormControl\u003cAnimal[]\u003e([]),\n  },\n  {\n    name: new FormControl(''),\n    maxCapacity: new FormControl(10),\n    animals: new FormControl\u003cAnimal[]\u003e([]),\n  },\n]);\n```\n\n\u003e The `NonNullable` version of this type is `NonNullableAngularFormArrayShallow`.\n\n## `AngularFormArray` Interface\n\nThis is a subset of the `AngularForm` interface that deeply converts an array over to the Angular\nTyped Forms system.\n\n```ts\ntype ZonesForm = AngularFormArray\u003cZone[]\u003e;\nconst zonesForm: ZonesForm = new FormArray([\n  {\n    name: new FormControl(''),\n    maxCapacity: new FormControl(10),\n    animals: new FormArray\u003cAnimalForm\u003e([]),\n  },\n  {\n    name: new FormControl(''),\n    maxCapacity: new FormControl(10),\n    animals: new FormArray\u003cAnimalForm\u003e([]),\n  },\n]);\n```\n\n\u003e The `NonNullable` version of this type is `NonNullableAngularFormArray`.\n\n## `AngularFormValue` Interface\n\nThis interface is used to translate the `.value` property type from a Angular Reactive Forms object.\nThis interface automatically accounts for the `Partial\u003c\u003e` nature of FormGroups since sub-controls\ncan be disabled. If you would like the whole form value regardless of disabled controls see\n`AngularFormRawValue` below.\n\n```ts\ntype AnimalForm = AngularForm\u003cAnimal\u003e;\n\nconst animalForm: AnimalForm = new FormGroup({\n  name: new FormControl(''),\n  species: new FormControl(''),\n  lifeStage: new FormControl({ value: '', disabled: true }),\n  birthDate: new FormControl(new Date('01 Jan 1994')),\n  alive: new FormControl(true),\n});\n\nconst animalValue: AngularFormValue\u003cAnimalForm\u003e = animalForm.value;\n/*\n{\n  name?: string | null;\n  species?: string | null;\n  lifeStage?: string | null;\n  birthDate?: Date | null;\n}\n*/\n```\n\nThis interface also works for custom implementations of the `AbstractControl` class.\n\n## `AngularFormRawValue` Interface\n\nThis interface is used to translate the `.getRawValue()` method return type from a Angular Reactive\nForms object. This will include all sub-controls regardless of their disabled state.\n\n```ts\ntype AnimalForm = AngularForm\u003cAnimal\u003e;\n\nconst animalForm: AnimalForm = new FormGroup({\n  name: new FormControl(''),\n  species: new FormControl(''),\n  lifeStage: new FormControl({ value: '', disabled: true }),\n  birthDate: new FormControl(new Date('01 Jan 1994')),\n  alive: new FormControl(true),\n});\n\nconst animalValue: AngularFormRawValue\u003cAnimalForm\u003e = animalForm.getRawValue();\n/*\n{\n  name: string | null;\n  species: string | null;\n  lifeStage: string | null;\n  birthDate: Date | null;\n}\n*/\n```\n\nThis interface also works for custom implementations of the `AbstractControl` class.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foasisdigital%2Fangular-typed-forms-helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foasisdigital%2Fangular-typed-forms-helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foasisdigital%2Fangular-typed-forms-helpers/lists"}