https://github.com/launchcodedev/api-fields
Class decorator to trim object fields in API responses
https://github.com/launchcodedev/api-fields
Last synced: about 2 months ago
JSON representation
Class decorator to trim object fields in API responses
- Host: GitHub
- URL: https://github.com/launchcodedev/api-fields
- Owner: launchcodedev
- License: mpl-2.0
- Created: 2020-04-26T21:45:59.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T04:28:15.000Z (over 2 years ago)
- Last Synced: 2025-04-03T06:12:36.578Z (3 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@lcdev/api-fields
- Size: 1.06 MB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# API Fields
[](https://www.mozilla.org/en-US/MPL/2.0/)
[](https://github.com/launchcodedev/api-fields/actions)
[](https://www.npmjs.com/package/@lcdev/api-fields)
[](https://bundlephobia.com/result?p=@lcdev/api-fields@latest)
A small utility package that enables an easy way to guarantee that your API doesn't return fields
that you didn't want it to.
```bash
yarn add @lcdev/[email protected]
```
You might want to reduce the duplication when extracting return values. Most of the time,
you want to return the same fields for the same entities, records, etc.
API Fields is a decorator for classes that gives you the ability to tie in to [`@lcdev/mapper`](https://github.com/launchcodedev/mapper),
specifically its `extract` function.
```typescript
import { ApiField } from '@lcdev/api-fields';
class User extends BaseEntity {
@ApiField()
id: number;
// we never want to give this back in API responses
// maybe it's private, or maybe we don't want consumers to depend on it
firstName: string;
lastName: string;
@ApiField() // works just fine on getters
get fullName() {
return `${this.firstName} ${this.lastName}`;
}
// here, we only want the API Fields of Permission in the nested field
@ApiField(() => Permission)
permission: Permission;
...
}
```
Under the hood, this creates a listing of the fields you want to expose. We
call them "API Fields" because this is usually the way you expose fields in
JSON API responses.
We can get that metadata about any given class with the `getAPIFields` function.
The object returned can actually be used directly in `@lcdev/mapper`.
```typescript
import { getApiFields } from '@lcdev/api-fields';
import { extract } from '@lcdev/mapper';
// getApiFields can be called anywhere to retrieve the `Extraction` object
const extraction = getApiFields(User);
// use the mapper package to take back only the fields you're interested in
const trimmedFields = extract(fullFields, extraction);
```
### Formats
- `@ApiField() propName`: extract `propName` as-is
- `@ApiField(() => PropertyType) propName`: extract the ApiFields of `PropertyType` as `propName`
- `@ApiField(() => [PropertyType]) propName[]`: map as array, extracting ApiFields of each element
- `@ApiField({ ... }) propName`: extract fields from `propName` (same as `@lcdev/mapper`)
- `@ApiField(false) propName`: don't include this field
### Renames
Renaming a field is supported, in the same way it is in `@lcdev/mapper`.
```typescript
import { ApiField } from '@lcdev/api-fields';
import { rename } from '@lcdev/mapper';
class ImageUpload {
@ApiField(rename('url'))
awsURL: string;
}
```
When being extracted, the field will be renamed.
### Transforms
Transforming a field is supported, in the same way it is in `@lcdev/mapper`.
```typescript
import { ApiField } from '@lcdev/api-fields';
import { transform } from '@lcdev/mapper';
class ImageUpload {
@ApiField(transform(v => v.replace('https:', '')))
awsURL: string;
}
```
### Alternatives
- [class-transformer](https://github.com/typestack/class-transformer)