{"id":15290773,"url":"https://github.com/yamamotok/dataobject","last_synced_at":"2026-05-09T00:38:21.234Z","repository":{"id":45885635,"uuid":"327174200","full_name":"yamamotok/dataobject","owner":"yamamotok","description":"Decorator-based utility for transformation (serialization/deserialization) between plain object and class instance, developed for TypeScript projects. An alternative to class-validator and class-transformer.","archived":false,"fork":false,"pushed_at":"2023-10-17T07:24:08.000Z","size":627,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T19:47:41.232Z","etag":null,"topics":["custom-transformation","dataobject","deserialization","json","marshaller","npm-package","serialization","transformation","transformer","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@yamamotok/dataobject","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/yamamotok.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":"2021-01-06T02:13:07.000Z","updated_at":"2024-01-25T23:46:18.000Z","dependencies_parsed_at":"2024-10-11T17:04:39.541Z","dependency_job_id":null,"html_url":"https://github.com/yamamotok/dataobject","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamamotok%2Fdataobject","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamamotok%2Fdataobject/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamamotok%2Fdataobject/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yamamotok%2Fdataobject/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yamamotok","download_url":"https://codeload.github.com/yamamotok/dataobject/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245232914,"owners_count":20581703,"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":["custom-transformation","dataobject","deserialization","json","marshaller","npm-package","serialization","transformation","transformer","typescript"],"created_at":"2024-09-30T16:09:24.140Z","updated_at":"2026-05-09T00:38:21.191Z","avatar_url":"https://github.com/yamamotok.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"DataObject\n------------\n\n[![codecov](https://codecov.io/gh/yamamotok/dataobject/branch/develop/graph/badge.svg?token=F7O9X2PWOJ)](https://codecov.io/gh/yamamotok/dataobject)\n[![npm version](https://badge.fury.io/js/%40yamamotok%2Fdataobject.svg)](https://badge.fury.io/js/%40yamamotok%2Fdataobject)\n\n## Main features\n\n- Transformation from a Class instance to a plain JavaScript object. (Serialization)\n- Transformation from plain a JavaScript object to a Class instance. (Deserialization)\n- Designed for TypeScript project, using [TypeScript decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).\n\n## Key concept\n\n- DataObject always takes **whitelist** approach. It means that;\n  + Only `@property` decorated property will be output (serialized) into plain JavaScript object.\n  + Only `@property` decorated property will be taken (deserialized) into class instance.\n\n## Limitation\n\n- Currently, Class inheritance is not supported.\n\n## Quick examples\n\n```typescript\nclass User {\n  @property()\n  @required()\n  userId!: string;\n\n  @property()\n  name: string = '';\n\n  @property()\n  postalAddress?: Address;\n\n  @property()\n  @context('factory', 'toPlain')\n  metadata: Record\u003cstring, unknown\u003e = {};\n\n  @property()\n  tags: Set\u003cstring\u003e = new Set();\n\n  static factory = createFactory(User);\n  static toPlain = createToPlain(User);\n}\n\nclass Address {\n  @property()\n  @required()\n  country!: string;\n\n  @property()\n  @required()\n  @context('!public')\n  @validator(isPostalCode)\n  postalCode!: string;\n\n  static factory = createFactory(Address);\n  static toPlain = createToPlain(Address);\n}\n\nfunction isPostalCode(code: string) {\n  return /^[\\d]{7}$/.test(code);\n}\n\nconst source = {\n  userId: 'e7cebd38-9e3a-4487-9485-b3e3be03cd32',\n  name: 'test user',\n  postalAddress: {\n    country: 'jp',\n    postalCode: '1234567',\n  },\n  metadata: {\n    lastLogin: 1622940893174,\n  },\n  tags: ['loyal', 'active'],\n};\n\n// Transformation from plain object to class instance. (deserialization)\nconst created = User.factory(source);\n\n// Transformation from class instance to plain object. (serialization)\nconst plain = User.toPlain(created, 'public');\n``` \n\n## Decorators\n\n### @property decorator \u0026 \"toPlain\" and \"factory\" static methods\n\nTo enable a Class to work as \"DataObject\", you should do first;\n- Implement at least one `@property` decorated property.\n- Implement `factory` static method by using `createFactory` utility.\n- Implement `toPlain` static method by using `createToPlain` utility.\n\nThe simplest class looks like;\n\n```typescript\nclass Entity {\n  @property()\n  id?: string;\n\n  static factory = createFactory(Entity);\n  static toPlain = createToPlain(Entity); \n}\n```\n\n### Value transformation for each types\n\nDataObject will look up at types given through TypeScript type system for transformation. \nIt is also possible to tell its type explicitly. Also, you can set your own transformer.\n\n\n#### string, number, boolean (primitives)\n\n```typescript\n@property\nname: string;\n```\n- In toPlain, value will be output as-is.\n- In factory, input value will be type-coerced.\n\n\n```typescript\n@property\ncode: number;\n```\n- In toPlain, value will be output as-is.\n- In factory, input value will be type-coerced. If the result is `NaN`, Error will be thrown.\n\n\n```typescript\n@property\nactive: boolean;\n```\n- In toPlain, value will be output as-is.\n- In factory, input value will be type-coerced.\n\n#### Custom class\n\n```typescript\n@property\nactive: CustomClass; // CustomClass is a \"DataObject\" which has factory and toPlain static methods.\n```\n- In toPlain, value will be transformed with using `CustomClass#toPlain()`.\n- In factory, value will be transformed with using `CustomClass#factory()`.\n\n#### array and Set\n\n```typescript\n@property\nlist: string[];\n```\n- In toPlain, each value in array will be output as-is.\n- In factory, each value in array will be taken as-is. (no type coercion)\n- Other types are same.\n\n```typescript\n@property({ type: () =\u003e CustomClass })\nlist: CustomClass[];\n```\n- Need to set `type` option to `@property` decorator.\n- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()`.\n  A special attribute `__type: CustomClass` will be added.\n- In factory, each value in array will be transformed with using `CustomClass#factory()`.\n\n```typescript\n@property({ type: () =\u003e [CustomClass, AnotherCustomClass] })\nlist: Array\u003cCustomClass | AnotherCustomClass\u003e; // Union type also works\n```\n- Need to set `type` option to `@property` decorator.\n- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()` or `AnotherCustomClass#toPlain()`.\n  A special attribute `__type: CustomClass` or `__type: AnotherCustomClass` will be added.\n- In factory, each value in array will be transformed with using `CustomClass#factory()` or `AnotherCustomClass#factory()`\n  according to a special attribute `__type`.\n\n```typescript\n@property()\nlist: Set\u003cstring\u003e;\n\n@property({ type: () =\u003e CustomClass })\nlist: Set\u003cCustomClass\u003e;\n```\n- Same as array\n\n#### object and Map\n\n```typescript\n@property\ndict: Record\u003cstring, string\u003e;\n```\n- In toPlain, each value in object will be output as-is.\n- In factory, each value in object will be taken as-is. (no type coercion)\n- Other type pairs (e.g. `Record\u003cstring, unknown\u003e`) are same.\n\n\n```typescript\n@property{ type: () =\u003e CustomClass }\ndict: Map\u003cstring, CustomClass\u003e;\n```\n- Need to set `type` options to `@property` decorator.\n- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()`.\n  A special attribute `__type: CustomClass` will be added.\n- In factory, each value in array will be transformed with using `CustomClass#factory()`.\n\n```typescript\n@property{ type: () =\u003e CustomClass, isMap: true }\ndict: Record\u003cstring, CustomClass\u003e;\n```\n- Need to set `type` and `isMap` options to `@property` decorator if you want to use object like ES6 Map.\n- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()`.\n  A special attribute `__type: CustomClass` will be added.\n- In factory, each value in array will be transformed with using `CustomClass#factory()`.\n\n```typescript\n@property{ type: () =\u003e [CustomClass, AnotherCustomClass] }\ndict: Map\u003cstring, CustomClass | AnotherCustomClass\u003e;\n```\n- Union type works same as array of union types.\n\n#### undefined\n- If the value given to factory was `undefined`, the value is not taken in.\n\n#### Custom transformation\n\nYou can use your own transformer by setting `transformer` option.\n\n```typescript\n  @property({ transformer: jsDateTransformer })\n  timestamp: Date = new Date();\n```\n\nPlease check `src/bundle/jsDateTransformer` for actual transformer implementation, which transformed JavaScript\n`Date` object to ISO date string and vice-versa.\n\n\n### @required\n\nIn case a property has been decorated with `@required`,\nfactory will check if the property really exists in given source.\n\n```typescript\n  @property()\n  @required()\n  id!: string;\n```\nError will be thrown if it is missing.\n\n\n### @context\n\nYou can make transformation work only in specific contexts.\n- factory method has \"factory\" context as default.\n- toPlain method has \"toPlain\" context as default.\n\n```typescript\nclass Entity {\n  @property()\n  @context('!response')\n  id: string;\n  \n  @property('response')\n  get name(): string { ... }\n}\n\nEntity.toPlain(instance, 'response');\n```\n\nYou can specify custom context to both toPlain and factory. Exclusion (heading `!`) is available.\nWith above example, toPlain will output only `name` into resulted object. \n\n\n### @spread\n\nYou can spread the value in `toPlain` process with using `@spread` decorator.\nAlso, you can give context option which works same as `@context`.\n\n```typescript\nclass Entity {\n  @property()\n  id: string = 'my-id'\n\n  @property\n  @spread\n  details?: Record\u003cstring, unknown\u003e = { item: 'value' }\n}\n\nEntity.toPlain(instance);\n```\n\nWith above example, `details` is spread, and the result should look like;\n```typescript\n{ id: \"my-id\", item: \"value\" }\n```\n\n### @validator\n\nYou can set validator function which is invoked in 'factory'.\n\nValidator function should return `true` or nothing (`undefined`) in case of success.  \nIn case of failure, it should return false or Error, or should throw Error.\n\nIf some validation failed, 'factory' will throw `ValidationError`. \nYou can check what properties failed by checking the error thrown.\n\n```typescript\nclass Entity {\n  @property()\n  @validator((v: string) =\u003e v.length \u003c= 4)\n  id?: string;\n\n  static factory = createFactory(Entity);\n  static toPlain = createToPlain(Entity);\n}\ntry {\n  const entity = Entity.factory({ id: 'a_little_too_long' });\n} catch (err) {\n  // err should be instance of ValidationError\n  // err.causes[0].key should be 'id'\n  // err.causes[0].error should be 'id validation failed'\n}\n```\n\nBe noted the validator will be applied after value transformation finished, \nthat means the argument validator takes is already transformed value. \n\n\n## License (MIT)\n\nCopyright (c) 2021 Keisuke Yamamoto\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyamamotok%2Fdataobject","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyamamotok%2Fdataobject","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyamamotok%2Fdataobject/lists"}