{"id":19419064,"url":"https://github.com/launchcodedev/mapper","last_synced_at":"2026-03-05T05:30:59.982Z","repository":{"id":42277099,"uuid":"258052916","full_name":"launchcodedev/mapper","owner":"launchcodedev","description":"Simple, declarative object transformations to map your data","archived":false,"fork":false,"pushed_at":"2023-01-06T04:03:32.000Z","size":1703,"stargazers_count":5,"open_issues_count":11,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-06T17:23:13.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@lcdev/mapper","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/launchcodedev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-23T00:30:39.000Z","updated_at":"2024-06-20T23:57:35.000Z","dependencies_parsed_at":"2023-02-05T06:46:36.401Z","dependency_job_id":null,"html_url":"https://github.com/launchcodedev/mapper","commit_stats":null,"previous_names":["servall/mapper"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/launchcodedev/mapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fmapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fmapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fmapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fmapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/launchcodedev","download_url":"https://codeload.github.com/launchcodedev/mapper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fmapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30111743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"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":[],"created_at":"2024-11-10T13:16:02.537Z","updated_at":"2026-03-05T05:30:59.720Z","avatar_url":"https://github.com/launchcodedev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Object Mapper\n[![Licensed under MPL 2.0](https://img.shields.io/badge/license-MPL_2.0-green.svg)](https://www.mozilla.org/en-US/MPL/2.0/)\n[![Build Status](https://github.com/launchcodedev/mapper/workflows/CI/badge.svg)](https://github.com/launchcodedev/mapper/actions)\n[![npm](https://img.shields.io/npm/v/@lcdev/mapper.svg)](https://www.npmjs.com/package/@lcdev/mapper)\n[![BundlePhobia](https://badgen.net/bundlephobia/minzip/@lcdev/mapper)](https://bundlephobia.com/result?p=@lcdev/mapper@latest)\n\nOur internal utility package for describing object transformations in javascript.\nThis package contains a few functions for extraction, property mapping and a few\nother types of transforms.\n\nAt the moment, the functions that this package exports have typescript types, but\nare not fully type safe. That is, we can't infer types correctly, so it's your\nresponsibility to cast as required. We think it may be possible to do in the future,\nand won't go 1.0 without at least knowing for sure.\n\n### Quick Start\n```bash\nyarn add @lcdev/mapper@0.1\n```\n\nThere are three main functions:\n\n1. The `extract` function: decides which fields of an object to keep, stripping others out.\n2. The `structuredMapper` function: transforms fields of an object, based on the key name of of that field.\n3. The `mapper` function: operates on all fields of an object, discriminating based on the type of values.\n\n# The `extract` Function\nExtraction is the simplest but most practical function. It take any javascript object in, and outputs a\nnew object with only the fields you want.\n\n```typescript\nimport { extract } from '@lcdev/mapper';\n\nconst user = await myDatabase.select('* from user where id = 1');\n\nconst userWithSpecificFields = extract(user, {\n  firstname: true,\n  lastname: true,\n  permissions: [{\n    role: true,\n    authority: ['access'],\n  }],\n});\n```\n\nFor this example, we'll pretend that `user` comes back as a nested object from an ORM.\n\n```typescript\nconst user = {\n  firstname: 'John',\n  lastname: 'Doe',\n  password: '$hashed',\n  socialSecurityNumber: '111222333',\n  permissions: [\n    {\n      role: 'admin',\n      authority: { access: 'read-write', id: 42 },\n      privateInfo: 'secret!',\n    },\n  ],\n};\n```\n\nGiven this, our `extract` function looks at the declarative object passed as a second argument,\nand decides which fields to keep and which to ignore.\n\nOur output looks like:\n\n```typescript\nconst userWithSpecificFields = {\n  firstname: 'John',\n  lastname: 'Doe',\n  permissions: [\n    { role: 'admin', authority: { access: 'read-write' } },\n  ],\n};\n```\n\nNotice how `password`, `privateInfo`, `id` and others were disgarded. This can be quite helpful for ensuring\nthat your API responses come back as you expect them to, especially when using an ORM where you don't want to\nbe manually selecting columns for every route.\n\n#### Patterns\nHere are the patterns that `extract` supports:\n\n- `['foo']` means \"pull these fields from the object\" - it's the same as `{ foo: true }`\n- `[{ ... }]` means \"map arrays, taking these fields\"\n- `{ foo: true }` means \"take only 'foo' from the object\"\n\nMismatching types, like an array selector when the return is an object, are ignored.\n\n# The `structuredMapper` Function\nThis function transforms a given javascript object into another, by transforming each field, by name.\n\n```typescript\nimport { structuredMapper } from '@lcdev/mapper';\n\nconst rawJsonResponse = await fetch('/foo/bar').then(v =\u003e v.json());\n\n// similar to extract, we give it data as the first argument, and how to map it in the second argument\nconst response = structuredMapper(rawJsonResponse, {\n  firstname: true,\n  lastname: true,\n  birthdate(value, dataType) {\n    return new Date(value);\n  },\n  eyeColor: {\n    optional: true,\n    map(value, dataTpe) {\n      return value;\n    },\n  },\n});\n```\n\nThe rules are pretty simple:\n- `true` means keep the value around\n- a named function means to pass the original value (and inferred DataType) to the function, and use the return value in the output\n- an object with a `map` function is like a named function, but allows `optional` and `nullable` meta properties\n- specifying `array: true` implies to map each element in an array, instead of assuming a single value\n- `fallback` is the value to use when an optional value isn't present in the input object\n- `rename` renames a field in the output object\n- `flatten` moves the field \"up\" in the object\n- `additionalProperties` passes through any fields that were on the input, but not specified in the mapping\n\nYou may find looking at our test suite for `structuredMapper` helpful, since these concepts in isolation don't tend to look practical.\n\n# The `mapper` Function\nSimilar to `structuredMapper`, the plain `mapper` function is a little more heavy-handed. It transforms all values, deeply nested.\n\n```typescript\nimport { mapper, Mapping, DataType } from '@lcdev/mapper';\nimport { isValid, parseISO } from 'date-fns';\n\nconst mapping: Mapping = {\n  custom: [\n    [\n      (data, dataType) =\u003e {\n        if (dataType === DataType.String) {\n          return isValid(parseISO(data));\n        }\n\n        return dataType === DataType.Date;\n      },\n      (data, dataType) =\u003e (dataType === DataType.Date) ? data : parseISO(data),\n    ],\n  ],\n};\n\nconst parseAllDates = (object) =\u003e mapper(object, mapping);\n```\n\nThis package will iterate through arrays, objects, etc. So doing an operation to all nested\nproperties of an object is easy.\n\nOur `parseAllDates` function deeply introspects the input object, and will transform any\nfields that look like a date.\n\nNotice that we used `custom` above. Let's look at the 'normal' case.\n\n```typescript\nconst mapping: Mapping = {\n  [DataType.Number]: num =\u003e num * 2,\n  [DataType.String]: str =\u003e {\n    const parsed = parseISO(str);\n    return isValid(parsed) ? parsed : str;\n  },\n};\n```\n\nThe more typical use of `mapper` differentiates based on `DataType`.\n\n## Alternatives\n- [class-transformer](https://github.com/typestack/class-transformer)\n- [ts-object-transformer](https://github.com/fcamblor/ts-object-transformer)\n- [ramda evolve](https://ramdajs.com/docs/#evolve)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchcodedev%2Fmapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaunchcodedev%2Fmapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchcodedev%2Fmapper/lists"}