Skip to content

Commit 426d83f

Browse files
arpit1503khannaarpit1503khanna
authored
docs(chore): copy the Readme to root as well (#210)
GH-209 ## Description Copy the Readme to root as well Fixes #209 ## Type of change Please delete options that are not relevant. - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Intermediate change (work in progress) ## How Has This Been Tested ? Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration - [ ] Test A - [ ] Test B ## Checklist: - [ ] Performed a self-review of my own code - [ ] npm test passes on your machine - [ ] New tests added or existing tests modified to cover all changes - [ ] Code conforms with the style guide - [ ] API Documentation in code was updated
1 parent 6213bf3 commit 426d83f

File tree

1 file changed

+303
-0
lines changed

1 file changed

+303
-0
lines changed

‎README.md

+303
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
<a href="https://sourcefuse.github.io/arc-docs/arc-api-docs" target="_blank"><img src="https://github.com/sourcefuse/loopback4-microservice-catalog/blob/master/docs/assets/logo-dark-bg.png?raw=true" alt="ARC By SourceFuse logo" title="ARC By SourceFuse" align="right" width="150" /></a>
2+
3+
# [loopback4-soft-delete](https://github.com/sourcefuse/loopback4-soft-delete)
4+
5+
<p align="left">
6+
<a href="https://www.npmjs.com/package/loopback4-soft-delete">
7+
<img src="https://img.shields.io/npm/v/loopback4-soft-delete.svg" alt="npm version" />
8+
</a>
9+
<a href="https://sonarcloud.io/summary/new_code?id=sourcefuse_loopback4-soft-delete" target="_blank">
10+
<img alt="Sonar Quality Gate" src="https://img.shields.io/sonar/quality_gate/sourcefuse_loopback4-soft-delete?server=https%3A%2F%2Fsonarcloud.io">
11+
</a>
12+
<a href="https://app.snyk.io/org/ashishkaushik/reporting?context[page]=issues-detail&project_target=%255B%2522sourcefuse%252Floopback4-soft-delete%2522%255D&project_origin=%255B%2522github%2522%255D&issue_status=%255B%2522Open%2522%255D&issue_by=Severity&table_issues_detail_cols=SCORE%257CCVE%257CCWE%257CPROJECT%257CEXPLOIT%2520MATURITY%257CAUTO%2520FIXABLE%257CINTRODUCED%257CSNYK%2520PRODUCT&v=1">
13+
<img alt="Synk Status" src="https://img.shields.io/badge/SYNK_SECURITY-MONITORED-GREEN">
14+
</a>
15+
<a href="https://github.com/sourcefuse/loopback4-soft-delete/graphs/contributors" target="_blank">
16+
<img alt="GitHub contributors" src="https://img.shields.io/github/contributors/sourcefuse/loopback4-soft-delete">
17+
</a>
18+
<a href="https://www.npmjs.com/package/loopback4-soft-delete" target="_blank">
19+
<img alt="downloads" src="https://img.shields.io/npm/dw/loopback4-soft-delete.svg">
20+
</a>
21+
<a href="https://github.com/sourcefuse/loopback4-soft-delete/blob/master/LICENSE">
22+
<img src="https://img.shields.io/github/license/sourcefuse/loopback4-soft-delete.svg" alt="License" />
23+
</a>
24+
<a href="https://loopback.io/" target="_blank">
25+
<img alt="Powered By LoopBack 4" src="https://img.shields.io/badge/Powered%20by-LoopBack 4-brightgreen" />
26+
</a>
27+
</p>
28+
29+
## Install
30+
31+
```sh
32+
npm install loopback4-soft-delete
33+
```
34+
35+
## Quick Starter
36+
37+
For a quick starter guide, you can refer to our [loopback 4 starter](https://github.com/sourcefuse/loopback4-starter) application which utilizes this package for soft-deletes in a multi-tenant application.
38+
39+
## Usage
40+
41+
The package exports following classes and mixins:
42+
43+
1. [SoftDeleteEntity](#softdeleteentity) - To add required soft delete props in the model.
44+
2. [SoftCrudRepository](#softcrudrepository) - Class providing soft crud capabilitiies (to be used in place of `DefaultCrudRepository`).
45+
3. [SoftCrudRepositoryMixin](#softcrudrepositorymixin) - Mixin accepting any respository that extends the DefaultCrudRepository to add soft delete functionality to. Can be used as a wrapper for `DefaultCrudRepository`, `DefaultTransactionalRepository` etc.
46+
4. [SoftDeleteEntityMixin](#softdeleteentitymixin)
47+
5. [DefaultTransactionSoftCrudRepository](#defaulttransactionsoftcrudrepository-deprecated) (Deprecated) - Class providing soft crud capabilitiies. To be used in place of `DefaultTransactionalRepository`.
48+
6. [SequelizeSoftCrudRepository](#sequelizesoftcrudrepository) - Class providing soft crud capabilitiies for [@loopback/sequelize](https://www.npmjs.com/package/@loopback/sequelize) package. To be used in place of `SequelizeCrudRepository`.
49+
50+
Following are more details on the usage of above artifcats:
51+
52+
### SoftDeleteEntity
53+
54+
An abstract base class for all models which require soft delete feature.
55+
This class is a wrapper over Entity class from [@loopback/repository](https://github.com/strongloop/loopback-next/tree/master/packages/repository) adding three attributes to the model class for handling soft-delete, namely, deleted, deletedOn, deletedBy.
56+
The column names needed to be there in DB within that table are - 'deleted', 'deleted_on', 'deleted_by'.
57+
If you are using auto-migration of loopback 4, then, you may not need to do anything specific to add this column.
58+
If not, then please add these columns to the DB table.
59+
60+
### SequelizeSoftCrudRepository
61+
62+
An abstract base class providing soft delete capabilities for projects using [@loopback/sequelize](https://www.npmjs.com/package/@loopback/sequelize) package.
63+
All the other workings are similar to [SoftCrudRepository](#softcrudrepository), except it's imported using directory import syntax from `loopback4-soft-delete/sequelize`.
64+
65+
### SoftCrudRepository
66+
67+
An abstract base class for all repositories which require soft delete feature.
68+
This class is going to be the one which handles soft delete operations and ensures soft deleted entries are not returned in responses, However if there is a need to query soft deleted entries as well, there is an options to achieve that and you can use findAll() in place of find() , findOneIncludeSoftDelete() in place of findOne() and findByIdIncludeSoftDelete() in place of findById(), these will give you the responses including soft deleted entries.
69+
This class is a wrapper over DefaultCrudRepository class from [@loopback/repository](https://github.com/strongloop/loopback-next/tree/master/packages/repository).
70+
71+
### DefaultTransactionSoftCrudRepository (Deprecated)
72+
73+
> Note: `DefaultTransactionSoftCrudRepository` is deprecated in favour of [SoftCrudRepositoryMixin](#softcrudrepositorymixin) and will be removed in future releases.
74+
75+
An abstract base class similar to [SoftCrudRepository](#softcrudrepository) but with transaction support.
76+
77+
This class is a wrapper over `DefaultTransactionalRepository` class from [@loopback/repository](https://github.com/strongloop/loopback-next/tree/master/packages/repository).
78+
79+
In order to use this extension in your application, please follow below steps.
80+
81+
1. Extend models with SoftDeleteEntity class replacing Entity. Like below:
82+
83+
```ts
84+
import {model, property} from '@loopback/repository';
85+
import {SoftDeleteEntity} from 'loopback4-soft-delete';
86+
87+
@model({
88+
name: 'users',
89+
})
90+
export class User extends SoftDeleteEntity {
91+
@property({
92+
type: 'number',
93+
id: true,
94+
})
95+
id?: number;
96+
97+
// .... More properties
98+
}
99+
```
100+
101+
2. Extend repositories with SoftCrudRepository class replacing DefaultCrudRepository. Like below:
102+
103+
```ts
104+
import {Getter, inject} from '@loopback/core';
105+
import {SoftCrudRepository} from 'loopback4-soft-delete';
106+
import {AuthenticationBindings, IAuthUser} from 'loopback4-authentication';
107+
108+
import {PgdbDataSource} from '../datasources';
109+
import {User, UserRelations} from '../models';
110+
111+
export class UserRepository extends SoftCrudRepository<
112+
User,
113+
typeof User.prototype.id,
114+
UserRelations
115+
> {
116+
constructor(
117+
@inject('datasources.pgdb') dataSource: PgdbDataSource,
118+
@inject.getter(AuthenticationBindings.CURRENT_USER, {optional: true})
119+
protected readonly getCurrentUser: Getter<IAuthUser | undefined>,
120+
) {
121+
super(User, dataSource, getCurrentUser);
122+
}
123+
}
124+
```
125+
126+
3. For transaction support, use the `SoftCrudRepositoryMixin` and wrap it around `DefaultTransactionalRepository`. Like below:
127+
128+
```ts
129+
import {Getter, inject} from '@loopback/core';
130+
import {SoftCrudRepository} from 'loopback4-soft-delete';
131+
import {AuthenticationBindings, IAuthUser} from 'loopback4-authentication';
132+
133+
import {PgdbDataSource} from '../datasources';
134+
import {User, UserRelations} from '../models';
135+
136+
export class UserRepository extends SoftCrudRepositoryMixin<
137+
User,
138+
typeof User.prototype.id,
139+
UserRelations
140+
>(DefaultTransactionalRepository) {
141+
constructor(
142+
@inject('datasources.pgdb') dataSource: PgdbDataSource,
143+
@inject.getter(AuthenticationBindings.CURRENT_USER, {optional: true})
144+
protected readonly getCurrentUser: Getter<IAuthUser | undefined>,
145+
) {
146+
super(User, dataSource, getCurrentUser);
147+
}
148+
}
149+
```
150+
151+
## Mixins Usage
152+
153+
The package also provides the following mixins which can be used for soft delete functionality:
154+
155+
### SoftDeleteEntityMixin
156+
157+
This mixin adds the soft delete properties to your model. The properties added are represented by the [IBaseEntity](#ibaseentity) interface:
158+
159+
There is also an option to provide config for the `@property` decorator for all these properties.
160+
161+
Usage of `SoftDeleteEntityMixin` is as follows:
162+
163+
```ts
164+
class Item extends Entity {
165+
@property({
166+
type: 'number',
167+
id: true,
168+
generated: true,
169+
})
170+
id?: number;
171+
172+
@property({
173+
type: 'string',
174+
required: true,
175+
})
176+
name: string;
177+
178+
constructor(data?: Partial<Item>) {
179+
super(data);
180+
}
181+
}
182+
183+
@model()
184+
export class ItemSoftDelete extends SoftDeleteEntityMixin(Item, {
185+
deletedBy: {
186+
name: 'deleted_by_userid',
187+
},
188+
}) {}
189+
```
190+
191+
#### IBaseEntity
192+
193+
The soft deleted properties added by [SoftDeleteEntityMixin](#softdeleteentitymixin) are represented by `IBaseEntity` interface.
194+
195+
```ts
196+
interface IBaseEntity {
197+
deleted?: boolean;
198+
deletedOn?: Date;
199+
deletedBy?: string;
200+
}
201+
```
202+
203+
### SoftCrudRepositoryMixin
204+
205+
You can make use of this mixin to get the soft delete functionality for `DefaultCrudRepository` or any respository that extends the `DefaultCrudRepository`. You need to extend your repository with this mixin and provide DefaultCrudRepository (or any repository that extends DefaultCrudRepository) as input. This means that this same mixin can also be used to provide soft delete functionality for DefaultTransactionSoftCrudRepository (as DefaultTransactionSoftCrudRepository extends DefaultCrudRepository). You will have to inject the getter for IAuthUser in the contructor of your repository.
206+
207+
#### Example:
208+
209+
```ts
210+
import {Constructor, Getter, inject} from '@loopback/core';
211+
import {DefaultCrudRepository} from '@loopback/repository';
212+
import {AuthenticationBindings, IAuthUser} from 'loopback4-authentication';
213+
import {SoftCrudRepositoryMixin} from 'loopback4-soft-delete';
214+
import {TestDataSource} from '../datasources';
215+
import {ItemSoftDelete, ItemSoftDeleteRelations} from '../models';
216+
217+
export class ItemRepository extends SoftCrudRepositoryMixin<
218+
ItemSoftDelete,
219+
typeof ItemSoftDelete.prototype.id,
220+
Constructor<
221+
DefaultCrudRepository<
222+
ItemSoftDelete,
223+
typeof ItemSoftDelete.prototype.id,
224+
ItemSoftDeleteRelations
225+
>
226+
>,
227+
ItemSoftDeleteRelations
228+
>(DefaultCrudRepository) {
229+
constructor(
230+
@inject('datasources.test') dataSource: TestDataSource,
231+
@inject.getter(AuthenticationBindings.CURRENT_USER)
232+
public getCurrentUser: Getter<IAuthUser>,
233+
) {
234+
super(ItemSoftDelete, dataSource);
235+
}
236+
}
237+
```
238+
239+
## Additional Repository Methods
240+
241+
Following are some additional methods that you can use when working with repositories in your application, either by extending the base repositories provided or by using the [SoftCrudRepositoryMixin](#softcrudrepositorymixin):
242+
243+
1. `findAll` - This method is similar to `find`, but it returns entries including soft deleted ones.
244+
2. `deleteHard` - This method is used to perform a hard delete on a specified entity.
245+
3. `deleteByIdHard` - This method is used to perform a hard delete of an entity based on the provided ID.
246+
4. `findByIdIncludeSoftDelete` - This method is similar to `findById`, but it returns the entity even if it is soft deleted.
247+
5. `deleteAllHard` - This method is used to perform a hard delete of multiple entities based on a specified condition.
248+
6. `findOneIncludeSoftDelete` - This method is similar to `findOne`, but it returns a single entity even if it is soft deleted.
249+
7. `countAll` - This method is similar to `count`, but it returns the total count of all entities including soft deleted ones.
250+
251+
### deletedBy
252+
253+
Whenever any entry is deleted using deleteById, delete and deleteAll repository methods, it also sets deletedBy column with a value with user id whoever is logged in currently. Hence it uses a Getter function of IUser type. However, if you want to use some other attribute of user model other than id, you can do it by overriding deletedByIdKey. Here is an example.
254+
255+
```ts
256+
import {Getter, inject} from '@loopback/core';
257+
import {SoftCrudRepository, IUser} from 'loopback4-soft-delete';
258+
import {AuthenticationBindings} from 'loopback4-authentication';
259+
260+
import {PgdbDataSource} from '../datasources';
261+
import {User, UserRelations} from '../models';
262+
263+
export class UserRepository extends SoftCrudRepository<
264+
User,
265+
typeof User.prototype.id,
266+
UserRelations
267+
> {
268+
constructor(
269+
@inject('datasources.pgdb') dataSource: PgdbDataSource,
270+
@inject.getter(AuthenticationBindings.CURRENT_USER, {optional: true})
271+
protected readonly getCurrentUser: Getter<User | undefined>,
272+
) {
273+
super(User, dataSource, getCurrentUser);
274+
}
275+
}
276+
```
277+
278+
Model class for custom identifier case. Notice the `getIdentifier() method` and `IUser` interface implemented.
279+
280+
```ts
281+
@model()
282+
class User extends SoftDeleteEntity implements IUser {
283+
@property({
284+
id: true,
285+
})
286+
id: string;
287+
288+
@property()
289+
username: string;
290+
291+
getIdentifier() {
292+
return this.username;
293+
}
294+
295+
constructor(data?: Partial<User>) {
296+
super(data);
297+
}
298+
}
299+
```
300+
301+
## License
302+
303+
[MIT](https://github.com/sourcefuse/loopback4-soft-delete/blob/master/LICENSE)

0 commit comments

Comments
 (0)