Coder Social home page Coder Social logo

troyanskiy / ngx-resource Goto Github PK

View Code? Open in Web Editor NEW
200.0 8.0 46.0 5.72 MB

Resource (REST) Client for Angular 2

Home Page: http://troyanskiy.github.io/ngx-resource/

TypeScript 92.32% JavaScript 6.41% HTML 0.94% SCSS 0.33%
angular-2 rest rest-api network requests

ngx-resource's Introduction

Unfortunately I don't have time to maintain the library. So PRs are more than welcome.



@ngx-resource/core @ngx-resource/handler-ngx-http @ngx-resource/handler-cordova-advanced-http @ngx-resource/handler-ngx-http-legacy
npm version npm version npm version npm version

@ngx-resource/core

Resource Core is an evolution of ngx-resource lib which provides flexibility for developers. Each developer can implement their own request handlers to easily customize the behavior. In fact, @ngx-resource/core is an abstract common library which uses ResourceHandler to make requests, so it's even possible to use the lib on node.js server side with typescript. You just need to implement a ResourceHandler for it.

All my examples will be based on angular 4.4.4+

Known ResourceHandlers

  • @ngx-resource/handler-ngx-http. Based on HttpClient from @angular/common/http. Includes ResourceModule.forRoot.
  • @ngx-resource/handler-ngx-http-legacy. Based on Http from @angular/http. Includes ResourceModule.forRoot.
  • @ngx-resource/handler-cordova-advanced-http. Based on Cordova Plugin Advanced HTTP.
  • @ngx-resource/handler-fetch. Besed on Fetch API. Not yet created.

Creation of Resource class

@Injectable()
@ResourceParams({
  // IResourceParams
  pathPrefix: '/auth'
})
export class MyAuthResource extends Resource {

  @ResourceAction({
    // IResourceAction
    method: ResourceRequestMethod.Post,
    path: '/login'
  })
  login: IResourceMethod<{login: string, password: string}, IReturnData>; // will make an post request to /auth/login

  @ResourceAction({
    // IResourceAction
    //method: ResourceRequestMethod.Get is by default
    path: '/logout'
  })
  logout: IResourceMethod<void, void>;
  
  constructor(handler: ResourceHandler) {
    super(handler);
  }
  
}

@Injectable()
@ResourceParams({
  // IResourceParams
  pathPrefix: '/user'
})
export class UserResource extends Resource {
  
  @ResourceAction({
    path: '/{!id}'
  })
  getUser: IResourceMethodPromise<{id: string}, IUser>; // will call /user/id
  
  @ResourceAction({
    method: ResourceRequestMethod.Post
  })
  createUser: IResourceMethodPromiseStrict<IUser, IUserQuery, IUserPathParams, IUser>;
  
  @ResoucreAction({
    path: '/test/data',
    asResourceResponse: true
  })
  testUserRequest: IResourceMethodPromiseFull<{id: string}, IUser>; // will call /test/data and receive repsponse object with headers, status and body
  
  constructor(restHandler: ResourceHandler) {
    super(restHandler);
  }
  
}

// Using created Resource
@Injectable
export class MyService {
  
  private user: IUser = null;

  constructor(private myResource: MyAuthResource, private userResource: UserResource) {}
  
  doLogin(login: string, password: string): Promise<any> {
    return this.myResource.login({login, password});
  }
  
  doLogout(): Promise<any> {
    return this.myResource.logout();
  }
  
  async loginAndLoadUser(login: string, password: string, userId: string): Promise<any> {
    await this.doLogin(login, password);
    this.user = await this.userResource.getUser({id: userId});
  }
  
}

Final url is generated by concatination of $getUrl, $getPathPrefix and $getPath methods of Resource base class.

Is used by ResourceParams decorator for class decoration

List of params:

  • url?: string; - url of the api server; default ''
  • pathPrefix?: string; - path prefix of the api; default ''
  • path?: string; - path of the api; default ''
  • headers?: any; - headers; default {}
  • body?: any; - default body; default null
  • params?: any; - default url params; default null
  • query?: any; - defualt query params; default null
  • rootNode?: string; - key to assign all body; default null
  • removeTrailingSlash?: boolean; - default true
  • addTimestamp?: boolean | string; - default false
  • withCredentials?: boolean; - default false
  • lean?: boolean; - do no add $ properties on result. Used only with toPromise: false default false
  • mutateBody?: boolean; - if need to mutate provided body with response body. default false
  • returnAs?: ResourceActionReturnType; - what type response should be returned by action/method . default ResourceActionReturnType.Observable
  • keepEmptyBody?: boolean; - if need to keep empty body object {}
  • requestBodyType?: ResourceRequestBodyType; - request body type. default: will be detected automatically. Check for possible body types in the sources of ResourceRequestBodyType. Type detection algorithm check here.
  • responseBodyType?: ResourceResponseBodyType; - response body type. default: ResourceResponseBodyType.JSON Possible body type can be checked here ResourceResponseBodyType.

Is used by ResourceAction decorator for methods.

List of params (is all of the above) plus the following:

  • method?: ResourceRequestMethod; - method of request. Default ResourceRequestMethod.Get. All possible methods listed in ResourceRequestMethod
  • expectJsonArray?: boolean; - if expected to receive an array. The field is used only with toPromise: false. Default false.
  • resultFactory?: IResourceResultFactory; - custom method to create result object. Default: returns {}
  • map?: IResourceResponseMap; - custom data mapping method. Default: returns without any changes
  • filter?: IResourceResponseFilter; - custom data filtering method. Default: returns true

Mainly used to set defaults.

Models

An object with built-in in methods to save, update, and delete a model. Here is an example of a User model.

Note: UserResource should be injected at the beginning in order to use static model method like User.get(<id>), User.query(), User.remove(<id>)

export interface IPaginationQuery {
  page?: number;
  perPage?: number;
}

export interface IGroupQuery extends IPaginationQuery {
  title?: string;
}

export interface IUserQuery extends IPaginationQuery {
  firstName?: string;
  lastName?: string;
  groupId?: number;
}

export interface IUser {
  id: number;
  userName: string;
  firstName: string;
  lastName: string;
  groupId: string;
}

export class GroupResource extends ResourceCRUDPromise<IGroupQuery, Group, Group> {
  
  constructor(restHandler: ResourceHandler) {
    super(restHandler);
  }
  
  $resultFactory(data: any, options: IResourceActionInner = {}): any {
    return new Group(data);
  }
  
}

export class Group extends ResourceModel {
  
  readonly $resource = GroupResource;

  id: number;
  title: string;
  
  constructor(data?: IGroup) {
    super();
    if (data) {
      this.$setData(data);
    }
  }
  
  $setData(data: IGroup) {
    this.id = data.id;
    this.title = data.title;
  }
  
}

export class UserResource extends ResourceCRUDPromise<IUserQuery, User, User> {
  
  constructor(restHandler: ResourceHandler) {
      super(restHandler);
  }
  
  $resultFactory(data: any, options: IResourceActionInner = {}): any {
    return new User(data);
  }
  
}

export class User extends ResourceModel implements IUser {

  readonly $resource = UserResource;

  id: number;
  userName: string;
  firstName: string;
  lastName: string;
  groupId: string;
  
  fullName: string; // generated from first name and last name
  
  constructor(data?: IUser) {
    super();
    if (data) {
      this.$setData(data);
    }
  }
  
  $setData(data: IUser): this {
    Object.assign(this, data);
    this.fullName = `${this.firstName} ${this.lastName}`;
    return this;
  }
  
  toJSON() {
    // here i'm using lodash lib pick method.
    return _.pick(this, ['id', 'firstName', 'lastName', 'groupId']);
  }

}


// example of using the staff
async someMethodToCreateGroupAndUser() {

  // Creation a group
  const group = new Group();
  group.title = 'My group';
  
  // Saving the group
  await group.$save();
  
  // Creating an user
  const user = new User({
    userName: 'troyanskiy',
    firstName: 'firstName',
    lastName: 'lastName',
    groupId: group.id
  });
  
  // Saving the user
  await user.$save();
  
  
  // Query data from server
  
  const user1 = await this.userResource.get('1');
  
  // or
  
  const user2: User = await User.get('id');
  
}

QueryParams Conversion

You can define the way query params are converted. Set the global config at the root of your app.

ResourceGlobalConfig.queryMappingMethod = ResourceQueryMappingMethod.<CONVERSION_STRATEGY>

{
  a: [{ b:1, c: [2, 3] }]
}

With <CONVERSION_STRATEGY> being one of the following:

Plain (default)

No conversion at all

Output: ?a=[Object object]

Bracket

All array elements will be indexed

Output: ?a[0][b]=10383&a[0][c][0]=2&a[0][c][1]=3

JQueryParamsBracket

Implements the standard $.params way of converting

Output: ?a[0][b]=10383&a[0][c][]=2&a[0][c][]=3

@ngx-resource/handler-ngx-http

It's implementation of ResourceHandler which uses Angular HttpClient

If you are using Angular 5, please use @ngx-resource/handler-ngx-http 5.x

How to install and setup it

& npm i --save @ngx-resource/core @ngx-resource/handler-ngx-http

In you app module

// AoT requires an exported function for factories
export function myHandlerFactory(http: HttpClient) {
    return new MyResourceHandler(http);
}

@NgModule({
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    HttpClientModule,

    // Default ResourceHandler uses class `ResourceHandlerHttpClient`
    ResourceModule.forRoot()
    
    // Or set you own handler
    //ResourceModule.forRoot({
    //  handler: { provide: ResourceHandler, useFactory: (myHandlerFactory), deps: [HttpClient] }
    //})
  ],
  declarations: [...],
  bootstrap: [...],
  entryComponents: [...],
  providers: [...]
})
export class AppModule {
}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.