@pamlight/ngx-client/README.md

The angular library for Pamlight client SDK

# Pamlight Angular Client SDK

[Pamlight](https://pamlight.com) is a service for managing realtime connections to your database with whatever technology it is powered by. This tool (Angular Client SDK) is used to connect an Angular 2+ project from client domains to pamlight endpoints at a high level.

## Getting started
For more detailed instructions and guides on client side integration, check [Pamlight client integration](https://docs.pamlight.com/guides/client/integrations) and also how Pamlight works, see our [official documentations here](https://pamlight.com/docs).

## Installation
Install pamlight angular client sdk via npm by running the following command: 
> `npm install @pamlight/ngx-client --save`

## Usage
Register the `NgxPamlightModule` in your app module (or any other module you want to use it).
 > `import { NgxPamlightModule } from '@pamlight/ngx-client';`

 ```typescript
import { NgxPamlightModule } from '@pamlight/ngx-client';

@NgModule({
  declarations: [],
  imports: [
    ...,
    NgxPamlightModule
  ],
  providers: [],
  bootstrap: []
})
export class AppModule {}
 ``` 

### Use `NgxPamlightService` service in your component or in another service like below:
```typescript
import { Component, OnInit } from '@angular/core';
import { NgxPamlightService } from '@pamlight/ngx-client';

@Component({
    selector: 'app-component-a',
    templateUrl: './component-a.component.html',
    styleUrls: ['./component-a.component.scss']
})
export class ComponentName implements OnInit {    
    constructor(
        private ngxPamlightService: NgxPamlightService
    ) { }

    ngOnInit() {
        // code actions here
    }
}
```

### Initialize
Connect Pamlight client by initializing with the service. Its is adviceable to run `init()` method in a singleton service so as to ensure only a single instance is running.
```typescript
import { Injectable } from '@angular/core';
import { NgxPamlightService } from '@pamlight/ngx-client';

@Injectable()
export class ServiceName {
    constructor(
        private ngxPamlightService: NgxPamlightService
    ) {
        this.initPamlight();
    }

    private initPamlight(): void {
        // replace `PROJECT_ID` with your project ID from Pamlight dashboard
        const projectId: string = `PROJECT_ID`;

        this.ngxPamlightService.init().then(() => {
            console.log('Pamlight connected successfully');
        }).catch(err => {
            throw Error(err);
        });
    }
}
```

### sync data from database
Reading and subscribing to data changes in your database is straight forward. The `read method` returns an rxjs observable which can be subscribe to for subsequent data changes. For example, to get a `User` document from data base by userId, you could do something like this:

```typescript
const routeId = 'getUserByUserID';
const query = {
    userId: `USER_ID`
};

this.ngxPamlightService.read<User>(routeId, query).subscribe(user => {
    console.log(user);
});
```

### write data to database
Writing data to your database is by calling the write method on the connected client object. This returns a promise object with result if expected or void otherwise.

```typescript
const routeId = 'updateUserProfile';
const payload = {
  firstName: 'Alice',
  lastName: 'Bob',
  age: 32
};

this.ngxPamlightService.write(routeId, payload, true).then((result) => {
  console.log(result);
}).catch((e) => {
  throw Error(e);
});
```

### Further Reading
For further reading and information, check more [client read operations](https://docs.pamlight.com/guides/client/reads) as well as [client write operations](https://docs.pamlight.com/guides/client/writes).