@acetex/flarestore 中文文档教程

Question

Welcom to Flarestore the ORM Firestore for node.js

** 重要的是这个包只是 开发阶段的开始 它有很多使用限制，如果你打算在生产中使用，请小心 **

Node.Js Firestore ORM 由 laravel 启发，非常简单和使用简单，超轻量级包装。

访问 Github 项目。

对不起我的英语。

Requirement and Limitation

1. This package support orWhere(), but it take extended price cost because firestore not have operator 'or' in where clause. every time your use 'orWhere()' the library must split request query to normal API where() and then merge union the data on every split request on your nodejs server.
2. This package not support firestore sub collection at all. the concept of this library your must imagine to RDB (Relational Data Base it just DB->TABLE->COLUMN schema and Relational data with foreign key, yes no need sub collection for RDB.
3. This Package not require a composite or single field index when your use orderBY() to sort your query, because the library use your nodejs server to do this.
4. Currently version not support difining field type, you can workaround to edit field type manualy on gcp firestore page.
5. Right now support LIKE for where() only, for orwhere() please wait to update next version.
6. Support ==, >, <, >=, <=, !=, array-contains, array-contains-any, in, not-in on where() operator same of gcp firestore.
7. Currently version suport only limit() not support startAt(), endAt().
8. Currently version not support realtime snapshot but you can workaround to get model instant property .activeTable it will return instant of firestore target collection then you can follow to use firestore official nude.js api sdk like realtime snapshot or other default official api.
9. Support MVC structure project as well, you can build Model with this flarestore package.

Installation

Before you begin

要对服务帐户进行身份验证并授权其访问 Firebase 服务，您必须生成一个 JSON 格式的私钥文件。

为您的服务帐户生成私钥文件：

1. 在 Firebase 控制台中，打开设置 > 服务帐户。

2. 点击生成新私钥，然后点击生成密钥进行确认。

3. JSON 密钥文件将下载到您的计算机，此密钥必须用于下一步的 .env 文件。

Install via npm

npm i @acetex/flarestore

Configulation

在 node.js 项目的根目录中创建 .env 文件。

#.env 

FS_KEY_FILENAME=[A path/to/file.json service account JSON key file on your computer]
FS_DB_NAME=[The name of firestore root collection for your database name]

Usage with Example

Create the model file

RDB 中的模型表示表例如，我们尝试在 models 目录中创建“用户”表

# /models/User.js
var FlareStore = require('@acetex/flarestore')

class User extends FlareStore {
    table = 'users'; // define the name of table

    // fillable field list
    fields = {
        'name': 'any', // any use for ignore validate data type for the future version
        'address': '5-gram' // use n-gram field type if you want to grant "Full Text Search" for this field, the perfix number tell the library split keyword with n digit, the small prefix number grant user countless typing frequency to get search result but bad system performance coz it make document size to large and using search time result more than higher prefix number. yes... becreaful to use n-gram number keep high prefix number as posible for performance.
    };

}

module.exports = User // export User model

创建用户

# /index.js
var User = require('./models/User.js');

async function createUser(){
    const user = new User;
    const params = {
        name: 'firstname lastname',
        address: 'example to use n-gram data type for Full Text Search'
    };

    await user.create(params); // when you create a new data record, the '__id' and '__timestamp' is automatic generated.
}

createUser();

获取用户并在其中查询然后更新当前用户

# /index.js
var User = require('./models/User.js');

async function getUser(){
    const user = new User;

    user.where('name', '==', 'firstname lastname');
    user.orWhere('address', 'customer address');
    user.orderBy('__timestamp', 'desc');

    let users = await user.get();
    users[0].name = 'firstname lastname changed!';
    users[0].save();
}

getUser();

搜索like operator with FULL TEXT SEARCH 此功能仅在字段类型设置为 n-gram 时使用，例如。 2-gram, 3-gram … 此版本仅支持where()，orWhere()等下个更新版本。

# /index.js
var User = require('./models/User.js');

async function getUser(){
    const user = new User;

    user.where('address', 'like', 'n-gram data type for Full Text search'); // no need type % block
    console.log(await user.get());

}

getUser();

首先删除记录

# /index.js
var User = require('./models/User.js');

async function deleteUser(){
    const user = new User;

    let users = await user.limit(3).get(); // limit only 3 record
    users[2].delete(); // delete user record by index position 3

}

deleteUser();

关系数据

：通过添加 post() 和 User->hasMany->Post 修改 User 模型并创建新的 Post model with Post->belongTo->User

# /models/User.js
var FlareStore = require('@acetex/flarestore')

class User extends FlareStore {
    table = 'users'; // define the name of table

    // fillable field list
    fields = {
        'name': 'string',
        'address': '5-gram'
    };

    post(){
        return this.hasMany('models/Post', 'users_id', '__id');
        // you can type just 'this.hasMany('models/Post')' if your foreignKey is {table name}_id
    }
}

module.exports = User // export User model

# /models/Post.js
var FlareStore = require('@acetex/flarestore')

class Post extends FlareStore {
    table = 'posts'; // define the name of table
    fields = ['title', 'description', 'uses_id'];

    fields = {
        'title': '3-gram',
        'description': '4-gram', // can use 2-gram, 3-gram, 4-gram ... n-gram
        'uses_id': 'string' //assume this key reference to 'user.__id' and the 'user.__id' auto generate to string data type by default.
    };

    user(){
        this.belongTo('models/User');
    }
}

module.exports = Post // export Post model

Secord：创建新的 'Post' record with 'users_id' foreignKey

# /index.js
var Post = require('./models/Post.js');

async function createPost(){
    const user = new User;
    let userData = await user.first();  // 'first()' return only first one record with 'object' not 'array of object'

    const post = new Post;
    const params = {
        title: 'test title',
        description: 'test description',
        users_id: userData.__id
    };

    await post.create(params); // when you create a new data record, the '__timestamp' field is automatic generated.
}

createPost();

第三：尝试检索关系模型；

# /index.js
var User = require('./models/User.js');
var Post = require('./models/Post.js');

async function getUser(){
    //example with hasMany
    const user = new User;

    let userData = await user.first();

    let posts = await userData.post().get();
    console.log(posts);

    // '.post()' is relation method to 'Post' model it will return 'Post' model object, of course you can use all property/method of 'Post' model like where(), orWhere(), orderBy(), etc. just like example below.
    let posts = await userData.post().where('description', 'test description').get();
    console.log(posts);


    //example with belongTo
    const postBelongTo = new Post;
    let postBelongToData = await postBelongTo.first();
    let belongToUser = postBelongToData.user().first();
    console.log(belongToUser);
}


getUser();

笔记！ hasOne() 使用与 hasMany() 相同的机制，但 返回类型 与 get() 方法有一些不同, hasOne() 返回单个对象，hasMany() 返回对象数组