{"id":20187972,"url":"https://github.com/arran4/tsobjectutils","last_synced_at":"2026-01-23T14:47:07.453Z","repository":{"id":62616412,"uuid":"561095646","full_name":"arran4/tsobjectutils","owner":"arran4","description":"Some typescript objects I use in a couple repos","archived":false,"fork":false,"pushed_at":"2025-12-20T07:50:42.000Z","size":306,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-22T13:21:29.257Z","etag":null,"topics":["json-deserialization","library","npm","npm-package","ts-library","ts-objects","tslang","tslibrary","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@arran4/tsobjectutils","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arran4.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-02T23:54:52.000Z","updated_at":"2025-12-20T07:50:34.000Z","dependencies_parsed_at":"2024-11-14T03:27:38.469Z","dependency_job_id":"36ae62f2-ca77-4e6a-ad31-a76b57ec4230","html_url":"https://github.com/arran4/tsobjectutils","commit_stats":{"total_commits":19,"total_committers":2,"mean_commits":9.5,"dds":0.1578947368421053,"last_synced_commit":"ded776aa2fcce7e2b6eeb229938021a296287e6b"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/arran4/tsobjectutils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arran4%2Ftsobjectutils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arran4%2Ftsobjectutils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arran4%2Ftsobjectutils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arran4%2Ftsobjectutils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arran4","download_url":"https://codeload.github.com/arran4/tsobjectutils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arran4%2Ftsobjectutils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28694457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T14:15:13.573Z","status":"ssl_error","status_checked_at":"2026-01-23T14:09:05.534Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["json-deserialization","library","npm","npm-package","ts-library","ts-objects","tslang","tslibrary","typescript"],"created_at":"2024-11-14T03:26:50.289Z","updated_at":"2026-01-23T14:47:07.444Z","avatar_url":"https://github.com/arran4.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tsobjectutils\n\n**tsobjectutils** provides helper functions to read values from untyped JavaScript objects and marshal them into TypeScript classes. These utilities help avoid runtime errors when parsing JSON or other data sources by validating and converting properties on the fly.\n\n## Why it exists\n\nWhen working with TypeScript, it's common to receive data from external sources like APIs or local storage. This data is often untyped, meaning that the shape of the object is not guaranteed. Accessing fields directly can lead to runtime errors, such as `TypeError: Cannot read property '...' of undefined`.\n\nThis library provides a set of helper functions that allow you to safely extract and convert values from untyped objects. This makes it easy to construct a class from loose JSON without sprinkling checks throughout your code.\n\n## How it helps\n\nBy using the helper functions provided by this library, you gain the following benefits:\n\n* **Type safety:** The helper functions ensure that the values you extract from untyped objects have the correct type.\n* **Null safety:** The helper functions handle null and undefined values gracefully, preventing runtime errors.\n* **Code clarity:** The helper functions make your code more readable and easier to understand.\n* **Reduced boilerplate:** The helper functions reduce the amount of boilerplate code you need to write.\n\n## Installation\n\n```bash\nnpm install @arran4/tsobjectutils\n```\n\n## Usage\n\nBelow is a simplified `User` model showing the intended pattern.\n\n```typescript\nimport {\n  GetStringPropOrDefault,\n  GetDatePropOrDefault,\n  GetBooleanPropOrDefault,\n  GetObjectPropOrThrow,\n  GetStringArrayPropOrDefault\n} from \"@arran4/tsobjectutils\";\n\nclass UserSettings {\n  constructor(\n    props: Partial\u003cRecord\u003ckeyof UserSettings, unknown\u003e\u003e | null = null,\n    public Theme: string = GetStringPropOrDefault(props, \"Theme\", \"light\")\n  ) {}\n}\n\nexport class User {\n  constructor(\n    props: Partial\u003cRecord\u003ckeyof User, unknown\u003e\u003e | null = null,\n    public UserUID: string = GetStringPropOrDefault(props, \"UserUID\", \"\"),\n    public Email: string = GetStringPropOrDefault(props, \"Email\", \"\"),\n    public Name: string = GetStringPropOrDefault(props, \"Name\", \"\"),\n    public Settings: UserSettings = GetObjectPropOrThrow\u003cUserSettings\u003e(props, \"Settings\"),\n    public Tags: string[] = GetStringArrayPropOrDefault(props, \"Tags\", []),\n    public Created: Date | null = GetDatePropOrDefault(props, \"Created\", null),\n    public Active: boolean = GetBooleanPropOrDefault(props, \"Active\", false)\n  ) {}\n}\n```\n\nCommon helpers can also be used independently:\n\n```typescript\nconst lastLogin = GetDatePropOrDefault(rawUser, \"LastLogin\", new Date());\nconst settings = GetObjectPropOrThrow\u003cUserSettings\u003e(rawUser, \"Settings\");\nconst roles = GetStringArrayPropOrDefault(rawUser, \"Roles\", []);\nconst isAdmin = GetBooleanPropOrDefault(rawUser, \"IsAdmin\", false);\n```\n\nBy relying on these helpers you gain:\n\n* a single constructor argument for easy copying of an object\n* safer unmarshalling of deserialized JSON objects\n\n## API summary\n\n- `GetStringPropOrDefault`, `GetStringPropOrDefaultFunction`, `GetStringPropOrThrow` – retrieve string properties\n- `GetNumberPropOrDefault`, `GetNumberPropOrDefaultFunction`, `GetNumberPropOrThrow` – retrieve numeric properties\n- `GetBigIntPropOrDefault`, `GetBigIntPropOrDefaultFunction`, `GetBigIntPropOrThrow` – retrieve bigint properties\n- `GetDatePropOrDefault`, `GetDatePropOrDefaultFunction`, `GetDatePropOrThrow` – parse dates and timestamps\n- `GetMapPropOrDefault`, `GetMapPropOrDefaultFunction`, `GetMapPropOrThrow` – retrieve map properties\n- `GetStringArrayPropOrDefault`, `GetStringArrayPropOrDefaultFunction`, `GetStringArrayPropOrThrow` – read arrays of strings\n- `GetDateArrayPropOrDefault`, `GetDateArrayPropOrDefaultFunction`, `GetDateArrayPropOrThrow` – read arrays of dates\n- `GetObjectPropOrDefault`, `GetObjectPropOrDefaultFunction`, `GetObjectPropOrThrow` – get nested objects\n- `GetObjectFunctionPropOrDefault`, `GetObjectFunctionPropOrThrow` – construct nested objects via a custom constructor\n- `GetObjectPropOrDefaultAllowNull`, `GetObjectPropOrDefaultFunctionAllowNull`, `GetObjectPropOrThrowAllowNull` – get nested objects, allowing null values\n- `GetObjectFunctionPropOrDefaultAllowNull`, `GetObjectFunctionPropOrThrowAllowNull` – construct nested objects via a custom constructor, allowing null values\n- `GetObjectArrayPropOrDefault`, `GetObjectArrayPropOrDefaultFunction`, `GetObjectArrayPropOrThrow`, `GetObjectArrayFunctionPropOrDefault`, `GetObjectArrayFunctionPropOrThrow` – work with arrays of objects\n- `GetBooleanPropOrDefault`, `GetBooleanPropOrDefaultFunction`, `GetBooleanFunctionPropOrDefault`, `GetBooleanPropOrThrow` – handle booleans\n- `ConstructorFunc\u003cT\u003e` – type for custom constructors\n- `ConstructorFuncAllowNull\u003cT\u003e` – type for custom constructors that allow null values\n\n## Running tests\n\nUse `npm test` to run the Jest suite and verify the utilities.\n\n## Links\n\n- [npm package](https://www.npmjs.com/package/@arran4/tsobjectutils)\n- [repository](https://github.com/arran4/tsobjectutils)\n\n## Related Projects\n\n- [dartobjectutils](https://github.com/arran4/dartobjectutils)\n- [go-objectutils](https://github.com/arran4/go-objectutils)\n\n## Definitions\n\n\u003c!-- grep 'export' src/index.ts | sed 's/ *{$/;/' | sort --\u003e\n\n```typescript\nexport function GetBigIntPropOrDefault\u003cR extends bigint | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): R;\nexport function GetBigIntPropOrDefaultFunction\u003cR extends bigint | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): R;\nexport function GetBigIntPropOrThrow\u003cR extends bigint | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, message?: string): R;\nexport function GetBooleanFunctionPropOrDefault(props:Record\u003cstring, unknown\u003e | undefined | null, prop:string, constructorFunc: (v: unknown) =\u003e boolean, defaultValue:boolean):boolean;\nexport function GetBooleanFunctionPropOrDefaultFunction(props:Record\u003cstring, unknown\u003e | undefined | null, prop:string, constructorFunc: (v: unknown) =\u003e boolean, defaultValue: () =\u003eboolean):boolean;\nexport function GetBooleanPropOrDefault(props:Record\u003cstring, unknown\u003e | undefined | null, prop:string, defaultValue:boolean):boolean;\nexport function GetBooleanPropOrDefaultFunction(props:Record\u003cstring, unknown\u003e | undefined | null, prop:string, defaultValue: () =\u003eboolean):boolean;\nexport function GetBooleanPropOrThrow(props:Record\u003cstring, unknown\u003e | undefined | null, prop:string, constructorFunc?: (v: unknown) =\u003e boolean):boolean;\nexport function GetDateArrayPropOrDefault\u003cR\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): Date[] | R;\nexport function GetDateArrayPropOrDefaultFunction\u003cR\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): Date[] | R;\nexport function GetDateArrayPropOrThrow(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string): Date[];\nexport function GetDatePropOrDefault\u003cR\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): R | Date;\nexport function GetDatePropOrDefaultFunction\u003cR\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): R | Date;\nexport function GetDatePropOrThrow(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string): Date;\nexport function GetMapPropOrDefault\u003cK, V, R\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): Map\u003cK, V\u003e | R;\nexport function GetMapPropOrDefaultFunction\u003cK, V, R\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): Map\u003cK, V\u003e | R;\nexport function GetMapPropOrThrow\u003cK, V\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, message?: string): Map\u003cK, V\u003e;\nexport function GetNumberPropOrDefault\u003cR extends number | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): R;\nexport function GetNumberPropOrDefaultFunction\u003cR extends number | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): R;\nexport function GetNumberPropOrThrow\u003cR extends number | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, message? : string): R;\nexport function GetObjectArrayFunctionPropOrDefault\u003cY, X extends Y[] | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFunc\u003cY\u003e, defaultValue: X): X;\nexport function GetObjectArrayFunctionPropOrThrow\u003cY, X extends Y[] | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFunc\u003cY\u003e, message? : string): X;\nexport function GetObjectArrayPropOrDefault\u003cY, X extends Y[] | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: X): X;\nexport function GetObjectArrayPropOrDefaultFunction\u003cY, X extends Y[] | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFunc\u003cY\u003e, defaultValue: () =\u003e X): X;\nexport function GetObjectArrayPropOrThrow\u003cY, X extends Y[] | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string): X;\nexport function GetObjectFunctionPropOrDefault\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFunc\u003cY\u003e, defaultValue: Y): Y;\nexport function GetObjectFunctionPropOrDefaultAllowNull\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFuncAllowNull\u003cY\u003e, defaultValue: Y): Y;\nexport function GetObjectFunctionPropOrThrow\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFunc\u003cY\u003e, message? : string): Y;\nexport function GetObjectFunctionPropOrThrowAllowNull\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFuncAllowNull\u003cY\u003e, message?: string): Y;\nexport function GetObjectPropOrDefault\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: Y): Y;\nexport function GetObjectPropOrDefaultAllowNull\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: Y): Y;\nexport function GetObjectPropOrDefaultFunction\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFunc\u003cY\u003e, defaultValue: () =\u003e Y): Y;\nexport function GetObjectPropOrDefaultFunctionAllowNull\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, constructorFunc: ConstructorFuncAllowNull\u003cY\u003e, defaultValue: () =\u003e Y): Y;\nexport function GetObjectPropOrThrow\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string): Y;\nexport function GetObjectPropOrThrowAllowNull\u003cY\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string): Y;\nexport function GetStringArrayPropOrDefault\u003cR\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): string[] | R;\nexport function GetStringArrayPropOrDefaultFunction\u003cR\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): string[] | R;\nexport function GetStringArrayPropOrThrow(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, message? : string): string[];\nexport function GetStringPropOrDefault\u003cR extends string | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultValue: R): R;\nexport function GetStringPropOrDefaultFunction\u003cR extends string | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, defaultFunction: () =\u003e R): R;\nexport function GetStringPropOrThrow\u003cR extends string | null\u003e(props: Record\u003cstring, unknown\u003e | undefined | null, prop: string, message? : string): R;\nexport type ConstructorFunc\u003cY\u003e = (params: object) =\u003e Y;\nexport type ConstructorFuncAllowNull\u003cY\u003e = (params: object | null) =\u003e Y;\n```\n\nCheck [Tests for example usage.](./src/index.test.ts)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farran4%2Ftsobjectutils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farran4%2Ftsobjectutils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farran4%2Ftsobjectutils/lists"}