https://github.com/arran4/tsobjectutils
Some typescript objects I use in a couple repos
https://github.com/arran4/tsobjectutils
json-deserialization library npm npm-package ts-library ts-objects tslang tslibrary typescript
Last synced: 5 months ago
JSON representation
Some typescript objects I use in a couple repos
- Host: GitHub
- URL: https://github.com/arran4/tsobjectutils
- Owner: arran4
- License: apache-2.0
- Created: 2022-11-02T23:54:52.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-12-20T07:50:42.000Z (6 months ago)
- Last Synced: 2025-12-22T13:21:29.257Z (6 months ago)
- Topics: json-deserialization, library, npm, npm-package, ts-library, ts-objects, tslang, tslibrary, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@arran4/tsobjectutils
- Size: 299 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tsobjectutils
**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.
## Why it exists
When 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`.
This 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.
## How it helps
By using the helper functions provided by this library, you gain the following benefits:
* **Type safety:** The helper functions ensure that the values you extract from untyped objects have the correct type.
* **Null safety:** The helper functions handle null and undefined values gracefully, preventing runtime errors.
* **Code clarity:** The helper functions make your code more readable and easier to understand.
* **Reduced boilerplate:** The helper functions reduce the amount of boilerplate code you need to write.
## Installation
```bash
npm install @arran4/tsobjectutils
```
## Usage
Below is a simplified `User` model showing the intended pattern.
```typescript
import {
GetStringPropOrDefault,
GetDatePropOrDefault,
GetBooleanPropOrDefault,
GetObjectPropOrThrow,
GetStringArrayPropOrDefault
} from "@arran4/tsobjectutils";
class UserSettings {
constructor(
props: Partial> | null = null,
public Theme: string = GetStringPropOrDefault(props, "Theme", "light")
) {}
}
export class User {
constructor(
props: Partial> | null = null,
public UserUID: string = GetStringPropOrDefault(props, "UserUID", ""),
public Email: string = GetStringPropOrDefault(props, "Email", ""),
public Name: string = GetStringPropOrDefault(props, "Name", ""),
public Settings: UserSettings = GetObjectPropOrThrow(props, "Settings"),
public Tags: string[] = GetStringArrayPropOrDefault(props, "Tags", []),
public Created: Date | null = GetDatePropOrDefault(props, "Created", null),
public Active: boolean = GetBooleanPropOrDefault(props, "Active", false)
) {}
}
```
Common helpers can also be used independently:
```typescript
const lastLogin = GetDatePropOrDefault(rawUser, "LastLogin", new Date());
const settings = GetObjectPropOrThrow(rawUser, "Settings");
const roles = GetStringArrayPropOrDefault(rawUser, "Roles", []);
const isAdmin = GetBooleanPropOrDefault(rawUser, "IsAdmin", false);
```
By relying on these helpers you gain:
* a single constructor argument for easy copying of an object
* safer unmarshalling of deserialized JSON objects
## API summary
- `GetStringPropOrDefault`, `GetStringPropOrDefaultFunction`, `GetStringPropOrThrow` – retrieve string properties
- `GetNumberPropOrDefault`, `GetNumberPropOrDefaultFunction`, `GetNumberPropOrThrow` – retrieve numeric properties
- `GetBigIntPropOrDefault`, `GetBigIntPropOrDefaultFunction`, `GetBigIntPropOrThrow` – retrieve bigint properties
- `GetDatePropOrDefault`, `GetDatePropOrDefaultFunction`, `GetDatePropOrThrow` – parse dates and timestamps
- `GetMapPropOrDefault`, `GetMapPropOrDefaultFunction`, `GetMapPropOrThrow` – retrieve map properties
- `GetStringArrayPropOrDefault`, `GetStringArrayPropOrDefaultFunction`, `GetStringArrayPropOrThrow` – read arrays of strings
- `GetDateArrayPropOrDefault`, `GetDateArrayPropOrDefaultFunction`, `GetDateArrayPropOrThrow` – read arrays of dates
- `GetObjectPropOrDefault`, `GetObjectPropOrDefaultFunction`, `GetObjectPropOrThrow` – get nested objects
- `GetObjectFunctionPropOrDefault`, `GetObjectFunctionPropOrThrow` – construct nested objects via a custom constructor
- `GetObjectPropOrDefaultAllowNull`, `GetObjectPropOrDefaultFunctionAllowNull`, `GetObjectPropOrThrowAllowNull` – get nested objects, allowing null values
- `GetObjectFunctionPropOrDefaultAllowNull`, `GetObjectFunctionPropOrThrowAllowNull` – construct nested objects via a custom constructor, allowing null values
- `GetObjectArrayPropOrDefault`, `GetObjectArrayPropOrDefaultFunction`, `GetObjectArrayPropOrThrow`, `GetObjectArrayFunctionPropOrDefault`, `GetObjectArrayFunctionPropOrThrow` – work with arrays of objects
- `GetBooleanPropOrDefault`, `GetBooleanPropOrDefaultFunction`, `GetBooleanFunctionPropOrDefault`, `GetBooleanPropOrThrow` – handle booleans
- `ConstructorFunc` – type for custom constructors
- `ConstructorFuncAllowNull` – type for custom constructors that allow null values
## Running tests
Use `npm test` to run the Jest suite and verify the utilities.
## Links
- [npm package](https://www.npmjs.com/package/@arran4/tsobjectutils)
- [repository](https://github.com/arran4/tsobjectutils)
## Related Projects
- [dartobjectutils](https://github.com/arran4/dartobjectutils)
- [go-objectutils](https://github.com/arran4/go-objectutils)
## Definitions
```typescript
export function GetBigIntPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): R;
export function GetBigIntPropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): R;
export function GetBigIntPropOrThrow(props: Record | undefined | null, prop: string, message?: string): R;
export function GetBooleanFunctionPropOrDefault(props:Record | undefined | null, prop:string, constructorFunc: (v: unknown) => boolean, defaultValue:boolean):boolean;
export function GetBooleanFunctionPropOrDefaultFunction(props:Record | undefined | null, prop:string, constructorFunc: (v: unknown) => boolean, defaultValue: () =>boolean):boolean;
export function GetBooleanPropOrDefault(props:Record | undefined | null, prop:string, defaultValue:boolean):boolean;
export function GetBooleanPropOrDefaultFunction(props:Record | undefined | null, prop:string, defaultValue: () =>boolean):boolean;
export function GetBooleanPropOrThrow(props:Record | undefined | null, prop:string, constructorFunc?: (v: unknown) => boolean):boolean;
export function GetDateArrayPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): Date[] | R;
export function GetDateArrayPropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): Date[] | R;
export function GetDateArrayPropOrThrow(props: Record | undefined | null, prop: string): Date[];
export function GetDatePropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): R | Date;
export function GetDatePropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): R | Date;
export function GetDatePropOrThrow(props: Record | undefined | null, prop: string): Date;
export function GetMapPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): Map | R;
export function GetMapPropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): Map | R;
export function GetMapPropOrThrow(props: Record | undefined | null, prop: string, message?: string): Map;
export function GetNumberPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): R;
export function GetNumberPropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): R;
export function GetNumberPropOrThrow(props: Record | undefined | null, prop: string, message? : string): R;
export function GetObjectArrayFunctionPropOrDefault(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFunc, defaultValue: X): X;
export function GetObjectArrayFunctionPropOrThrow(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFunc, message? : string): X;
export function GetObjectArrayPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: X): X;
export function GetObjectArrayPropOrDefaultFunction(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFunc, defaultValue: () => X): X;
export function GetObjectArrayPropOrThrow(props: Record | undefined | null, prop: string): X;
export function GetObjectFunctionPropOrDefault(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFunc, defaultValue: Y): Y;
export function GetObjectFunctionPropOrDefaultAllowNull(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFuncAllowNull, defaultValue: Y): Y;
export function GetObjectFunctionPropOrThrow(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFunc, message? : string): Y;
export function GetObjectFunctionPropOrThrowAllowNull(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFuncAllowNull, message?: string): Y;
export function GetObjectPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: Y): Y;
export function GetObjectPropOrDefaultAllowNull(props: Record | undefined | null, prop: string, defaultValue: Y): Y;
export function GetObjectPropOrDefaultFunction(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFunc, defaultValue: () => Y): Y;
export function GetObjectPropOrDefaultFunctionAllowNull(props: Record | undefined | null, prop: string, constructorFunc: ConstructorFuncAllowNull, defaultValue: () => Y): Y;
export function GetObjectPropOrThrow(props: Record | undefined | null, prop: string): Y;
export function GetObjectPropOrThrowAllowNull(props: Record | undefined | null, prop: string): Y;
export function GetStringArrayPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): string[] | R;
export function GetStringArrayPropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): string[] | R;
export function GetStringArrayPropOrThrow(props: Record | undefined | null, prop: string, message? : string): string[];
export function GetStringPropOrDefault(props: Record | undefined | null, prop: string, defaultValue: R): R;
export function GetStringPropOrDefaultFunction(props: Record | undefined | null, prop: string, defaultFunction: () => R): R;
export function GetStringPropOrThrow(props: Record | undefined | null, prop: string, message? : string): R;
export type ConstructorFunc = (params: object) => Y;
export type ConstructorFuncAllowNull = (params: object | null) => Y;
```
Check [Tests for example usage.](./src/index.test.ts)