metal-data v1.4.0
MetalData
Typescript REST API Client Library
Driver
Exambple
import { MetalDriver } from 'src/lib/metal-data/driver';
const driver = new MetalDriver();Origin
Example
import { MetalDriver } from 'src/lib/metal-data/driver';
import { MetalOrigin } from 'src/lib/metal-data/origin';
const driver = new MetalDriver();
const origin = new MetalOrigin(driver, { name: 'default', baseURL: 'http://localhost:3000' });Multiple Origin
import { MetalDriver } from 'src/lib/metal-data/driver';
import { MetalOrigin } from 'src/lib/metal-data/origin';
const driver = new MetalDriver();
const userAPI = new MetalOrigin(driver, { name: 'user-api', baseURL: 'http://localhost:3000' });
const projectAPI = new MetalOrigin(driver, { name: 'project-api', baseURL: 'http://localhost:3001' });Collection
Example
import { MetalDriver } from 'src/lib/metal-data/driver';
import { MetalOrigin } from 'src/lib/metal-data/origin';
import { MetalCollection } from 'src/lib/metal-data/collection';
import { MetalData } from 'src/lib/metal-data/record';
interface User extends MetalData {
first_name: string;
last_name: string;
age: number;
}
const driver = new MetalDriver();
const userAPI = new MetalOrigin(driver, { name: 'user-api', baseURL: 'http://localhost:3000' });
const users = new MetalCollection<User>(userAPI, { name: 'user', endpoint: 'users' });
// List all users.
users.find().then(items => {
items.forEach(item => console.log(item.first_name));
});
// List with filters.
users.find({
where: {
age: {
gt: 10
}
},
orderBy: {
age: 'desc'
}
}).then(console.log);
// Get single record.
users.findOne('9892394888').then(item => console.log(item.first_name));Query
A .find() method is a simple one-way method to perform a listing of a Collection and will returns a plain array. While
using .query(), it will return a Query object, so we can re-use the filters and caching.
Example
const adults = users.query({
where: {
age: {
gt: 10
}
}
});
adults.fetch().then(records => {
records.forEach(record => console.log(record.data.first_name));
});Query will store the fetched data into the records property. Whenever we call the .query() method, it will return
the previous query with its filters and data. The records will be replaced if call the
.fetch() method.
Example
const adults = users.query();
adults.records.forEach(record => console.log(record.data.first_name));With Query, we can manage all the fetched records at once.
Manage Users with Find
const allUsers = await users.find();
allUsers.forEach(user => users.update(user.id, { fisrt_name: 'updated' }));Manage Users with Query
const query = users.query();
await query.fetch();
await query.updateAll({ first_name: 'updated' });If we want to have multiple queries with different filters, we can use a named query.
Example
const allUsers = users.query();
const adultUsers = users.query('adults', { where: { age: { gt: 10 } } });We can update the filters later.
Example
const adultUsers = users.query('adults');
adultUsers.where({ age: { gt: 10 }, gender: { eq: 'male' } });
await adultUsers.fetch();Record
The .findOne() method will return a plain object with no helper, so we can't manage the data directly from the
returned object. With Record, we can cache the data and manage the data directly from there.
Using .findOne()
const me = await users.findOne(882823949);
console.log(me.first_name);
await users.update(me.id, { first_name: 'Updated First Name' });
console.log(me.first_name);Using Record
const me = users.get('882823949');
await me.fetch();
console.log(me.data.first_name);
await me.update({ first_name: 'Updated First Name' });
console.log(me.data.first_name);Using Record also allow us to assign form directly to the record data, so we can save it once the form complete.
Saving Record
const me = users.get('8928394999');
await me.fetch();
me.data.first_name = 'Name Updated';
await me.save();Where Filters
The .find(), and .query() method accepts where filters. There are two types of filters, AND condition and OR
conditions.
Passing the filter with an Object will mark the filter as AND condition, and passing the filter with an Array will
mark the filter as OR condition.
AND filters
users.find({
where: {
first_name: 'John',
last_name: 'Smith'
}
});The filter above means looking for users with fisrt_name == "John" AND last_name == "Smith".
OR filters
users.find({
where: [
{
first_name: 'John'
},
{
first_name: 'Michael'
}
]
});The filter above means looking for users with fisrt_name == "John" OR first_name == "Michael".
OR condition inside AND condition
users.find({
where: {
first_name: ['John', 'Michael'],
age: {
gt: 10
}
}
});The filter above means looking for users with (first_name == "John" OR first_name == "Michael") AND age > 10.
AND condition inside OR condition
users.find({
where: [
{
first_name: 'John',
age: {
gt: 10
}
},
{
first_name: 'Michael',
age: {
gt: 15
}
}
]
});The filters above means looking for users
with (first_name == "John" AND age > 10) OR (fisrt_name == "Michael" AND age > 15).
Transaction Middleware
By default, Metal Data will use an axios middleware to handle the requests. With a middleware, you can add a function to transform the request and the response, even a custom handler to run the transaction to forward the requests to 3rd party services such Algolia.
A middleware is a function that accept transaction object and next function to continue to the next middlewares.
When adding a middleware, please note that the default axios middleware will be ignored, so you must manually add it if
you want to keep using it. A middleware also must return the next call to proceed the next middlewares.
Example
const origin = new MetalOrigin({ baseURL: 'http://localhost:8000' });
function addJWT(trx, next) {
if (trx.status !== 'complete') {
trx.configs.headers['Authorization'] = `Bearer ${token}`;
}
return next();
}
function transformResponse(trx, next) {
const { meta, users } = trx.response.data
trx.response.data = { meta, data: users };
}
origin
.use(addJWT)
.use(origin.http())
.use(transformResponse);The example above will modify the transaction object and adds an JWT authorization before requesting to the server.
The transformResponse middleware will modify the response object so MetalData will understand the data structure.
Another scenario to use middleware is if you want to forward the query requests to algolia but keep the
POST, PUT, and DELETE requests for REST API. To do that you need to add two middleware and both of them must run
the transaction. To prevent duplicate request, on the REST API middleware you must only run the transaction if the
transaction status is not completed.
Example
function algolia() {
const client = algoliasearch(config);
return async (trx, next) => {
if (trx.request.listing) {
await trx.run(async () => {
const { hits } = await client.initIndex('INDEX').search();
return {
status: 200,
statusText: 'Success',
headers: {},
data: {
meta: {},
data: hits
}
};
});
}
return next();
}
}
function http() {
const client = axios.create(config);
return async (trx, next) => {
if (trx.status !== 'complete') {
await trx.run(async (configs) => {
return await client.request(configs);
});
}
return next();
}
}
origin
.use(algolia())
.use(addJWT)
.use(http())
.use(transformResponse)Angular Usage
interface User extends MetalData {
fisrt_name: string;
}
@Injectable({ providedIn: 'root' })
class Driver extends MetalDriver {}
@Injectable({ providedIn: 'root' })
class UserAPI extends MetalOrigin {
constructor(driver: Driver) {
super(driver, { name: 'user-api', baseURL: 'http://localhost:3000' });
}
}
@Injectable({ providedIn: 'root' })
class Users extends MetalCollection<User> {
constructor(origin: UserAPI) {
super(origin, { name: 'user', endpoint: 'users' });
}
}
@Component({
selector: 'app-test',
tempalte: '<p *ngFor="let user of query.records">{{user.data.first_name}}</p>'
})
class AppTestComponent {
public query: MetalQuery<User>;
constructor(collection: Users) {
this.query = collection.query();
this.query.fetch();
}
}