scorocode-js-sdk v0.2.0

Scorocode JS SDK v2

Установка

На данный момент библиотека не опубликована в реестре npm, поэтому сначала тянем код с гита, а потом добавляем в проект

yarn add file:/path/to/local/scorocode-js-sdk-folder

Разработка

В качестве стартера использован typescript-lib-starter, подробнее о сборке и доступных командах можно узнать на странице проекта

Основные команды

• Собрать проект

yarn build

• Протестировать проект

yarn test

• Автоформатировать код

yarn style:fix

Описание

Менеджер приложений

Работа с приложением скорокода начинается с менеджера приложений

// Импортируем менеджер приложений
// Он отвечает за инициализацию, хранение и утилизацию приложений
const sc = require('scorocode-js-sdk')

// Инициируем приложение по умолчанию
const app = sc.initApp({
  host: 'app.scorocode.test',
  port: 9000,
  ssl: false,
})
// Данное приложение будет доступно без указания его идентификатора
cosnt appRef = sc.app()
console.log(appRef === app) // true

// Создадим еще одно приложение с идентификатором 'anotherAppKey'
const anotherApp = sc.initApp({ host: 'anotherAppId.scorocode.ru' }, 'anotherAppKey')
// Данное приложение будет доступно с указанием его идентификатора
const anotherAppRef = sc.app('anotherAppKey')
console.log(anotherAppRef === anotherApp) // true

// Удалить приложение по умолчанию
sc.removeApp().then(() => {
  console.log('Default application removed!')
})

// Удалить приложение по идентификатору
sc.removeApp('anotherAppKey').then(() => {
  console.log('"anotherAppKey" application removed!')
})

В браузерном окружении менеджер приложений будет доступен из глобальной переменной window.scorocode

Приложение

Приложение предоставляет апи для работы с сервисами скорокод приложения (client, auth, fs, pg, pgManager)

const sc = require('scorocode-js-sdk')
const app = sc.initApp({ ... })

// все сервисы доступны не как свойство приложения, а через вызов функции
const clientService = sc.app().client()
const authService = sc.app().auth()
// etc

// events
app.on('onRequest', (request) => {
  // событие срабатывает при каждом обращении к апи приложения, перед отправкой запроса
})

app.on('onRequestSuccess', (response, request) => {
  // событие срабатывает при успешном выполнении запроса к апи приложения
})

app.on('onRequestError', (error, request) => {
  // событие срабатывает при ошибке во время выполнения запроса к апи приложения
})

Сервисы

• client - HTTP клиент

const sc = require('scorocode-js-sdk')
const app = sc.initApp({ ... })

// HTTP клиент предоставляет низко уровневые методы для вызова http апи скорокод приложения
// данный сервис используется другими сервисами сдк для сообщения с бэкендом скорокод приложения
const client = sc.app().client()
// http сервис состоит из нескольких подсервисов:
// auth - авторизия
// pg - postgreDB
// fs - файловый менеджер
// core - брокер апи

// просмотр папки
client.fs.folderRead('foo/bar').then((items) => console.log(items))
// получить список процессов
client.core.processes().then((items) => console.log(items))
// etc

• fs - сервис для работы с файлами

const sc = require('scorocode-js-sdk')
const app = sc.initApp({ ... })

const fs = sc.app().fs()

// Работа с папками
// Создание указателя на папку
const folder = fs.folder('path/to/folder')
// Синхронизировать с приложением и получить информацию о папке
folder.sync().then((folder) => {
  console.log('File list', folder.files)  // список указателей на папки/файлы
})
// Переименовать папку
folder.rename('newPath/to/folder').then((folder) => {
  console.log('Path', folder.path)  // 'newPath/to/folder'
})
// Удалить папку
folder.delete().then((folder) => {
  console.log('Folder deleted')
})

// Работа с файлами
// Создание указателя на фаил
const file = fs.file('path/to/file')
// Синхронизировать с приложением и получить информацию о файле
file.sync().then((file) => {
  console.log('File list', file.content)  // Blob буфер с контентом файла
})
// Переименовать файл
file.rename('newPath/to/file').then((file) => {
  console.log('Path', file.path)  // 'newPath/to/file'
})
// Удалить файл
file.delete().then((file) => {
  console.log('File deleted')
})

• pg - сервис баз данных postgre (публичное апи)

const sc = require('scorocode-js-sdk')
const app = sc.initApp({ ... })

// - для синхронизации сущности с приложением предусмотрено 2 метода: sync() и realSync()
// - realSync() - на данный момент не реализован и предусмотрен для синхронизации в режиме реального времени



// Документы (Document)

// Получить объект-ссылку на документ
const document = sc.app().pg().document('dbId', 'schemaName', 'collectionName', 'docId')

// Создать объект-ссылку на новый документ
const document = sc.app().pg().document('dbId', 'schemaName', 'collectionName')

// Синхронизация - загрузка данных документа
document.sync().then((document) => {
  console.log(document.attributes)
})

// Realtime cинхронизация
const unsubscribe = document.realSync(
(document) => {
  console.log('Document changed', document.attributes)
},
(error) => {
  console.log('Something goes wrong', error)
})
// отписаться от уведомлений
unsubscribe()

// Сохранить изменения
document.set('price', 100)
document.save().then((document) => {
  console.log(document.attributes) // { price: 100, ... }
})

// Создать документ
const newDocument = sc.app().pg().database('dbId').schema('test').collection('users').document()
newDocument.attributes = { foo: 'bar' }
newDocument.save().then((document) => {
  console.log(document.id) // new document id
  console.log(document.attributes) // { id: '123...', foo: 'bar' }
})

// Удалить документ
document.delete().then((document) => {
  console.log('Документ удален')
  console.log(document.isDeleted) // true
})

// Работа с данными документа
// Получить объект с данными документа
// Данные не передаются по ссылке, создается копия данных
const document = sc.app().pg().document('myDb', 'test', 'users')  // новый документ

document.attributes = { price: 10 } // установим значения
const attributes = document.attributes  // получим значения
console.log(attributes) // { price: 10 }
// любые изменения полученного объекта с данными не приведет к изменению документа
attributes.price = 20
console.log(document.attributes) // { price: 10 }

// Установить значения документа
document.attributes = { name: 'Profuct', price: 100 }
// или
document.setAttributes({ name: 'Profuct', price: 100 })

// Установить значение поля документа
document.set('price', 55)

// Получить значение поля документа
console.log(document.get('price'))  // 55

// Можно установить и получить вложенные значения
document.set('a[0].b.c', 'value')
console.log(document.get('a[0].b.c')) // 'value'
// или
document.set(['a', '0', 'b', 'c'], 'newValue')
console.log(document.get(['a', '0', 'b', 'c'])) // 'newValue'

// Merge - рекурсивное объединение данных
document.attributes = {
  a: 'A',
  b: 'B',
  o: {
    foo: 'foo'
  },
}
document.merge({
  b: 'b',
  o: {
    foo: 'FOO',
    bar: 'bar',
  },
  c: 'c'
})
console.log(document.attributes)
/*
{
  a: 'A',
  b: 'b',
  o: {
    foo: 'FOO',
    bar: 'bar',
  },
  c: 'c'
}
*/

// Assign - объединение данных
document.attributes = {
  a: 'A',
  b: 'B',
  o: {
    foo: 'foo'
  },
}
document.assign({
  b: 'b',
  o: {
    bar: 'bar',
  },
  c: 'c'
})
console.log(document.attributes)
/*
{
  a: 'A',
  b: 'b',
  o: {
    bar: 'bar',
  },
  c: 'c'
}
*/

// set* методы документа позволяют выстраивать цепочку обращений к документу
document
  .setAttributes({ a: '', b: '' })
  .set('a', 'A')
  .set('b', 'B')
  .assign({ c: 'C' })
  .merge({ a: 'AA', b: 'BB' })
  .save()



// Запросы к БД (Query)

// Создать объект-запрос к бд
const query = sc.app().pg().query('dbId', 'schemaName', 'collectionName')

// Работа с запросом
query
  .from(10)                       // получить записи после 10ой
  .limit(15)                      // лимит в 15 записей
  .orderBy('name', 'ascend')      // сортировать по имени по возрастанию
  .orderBy('price', 'descend')    // сортировать по цене по убыванию
  .filterBy({                     // фильтровать опубликованные записи
    isPublished: true,
  })
  .find()                         // получить записи
  .then((items) => {
    // items - массив документов (Document)
    console.log('Items', items)
  })

• pgManager - сервис баз данных postgre (админское апи)

const sc = require('scorocode-js-sdk')
const app = sc.initApp({ ... })

// Структура БД Porstgre состоит из сущностей:
// - база данных
// - схема
// - коллекция (таблица)
// - документ (запись в таблице)
// АПИ сервиса баз данных устроено таким образом:
// - для каждой сущности есть соответсвующий объект-ссылка, содержащий апи для работы с данной сущностью
// - сущности выстроены в иерархию: сервис БД создает ссылки на базы данных, базы данных пораждают схемы,
//   схемы пораждают коллекции, коллекции пораждают документы
// - для синхронизации сущности с приложением предусмотрено 2 метода: sync() и realSync()
// - realSync() - на данный момент не реализован и предусмотрен для синхронизации в режиме реального времени



// База данных (Database)

// Получить объект-ссылку на БД
const db = sc.app().pgManager().database('dbId')

// Синхронизация - загрузка метаданных и схем БД
db.sync().then((db) => {
  console.log(db.info)
  console.log(db.schemas)
})

// Создать БД
const newDb = sc.app().pgManager().database('newDbId')
db.create({
  name: 'myNewDB'
}).then((db) => {
  console.log(db.info)
})

// Удалить БД
sc.app().pgManager().database('testDbId')
  .drop()
  .then((db) => {
     console.log('БД удалена')
  })

// Создать объект-ссылку на схему БД
const schema = sc.app().pgManager().database('dbId').schema('schemaName')



// Схемы (Schema)

// Получить объект-ссылку на схему БД
const schema = sc.app().pgManager().database('dbId').schema('test')

// Синхронизация - загрузка метаданных схемы и списка ее коллекций
schema.sync().then((schema) => {
  console.log(schema.info)
  console.log(schema.collections)
})

// Создать схему
const newSchema = sc.app().pgManager().database('dbId').schema('newSchema')
newSchema.create().then((schema) => {
  console.log(schema.info)
})

// Удалить схему
sc.app().pgManager().database('dbId').schema('testSchema')
  .drop()
  .then((schema) => {
     console.log('Схема удалена')
  })

// Создать объект-ссылку на схему коллекцию
const collection = sc.app().pgManager().database('dbId').schema('schemaName').collection('collectionName')



// Коллекции (Collection)

// Получить объект-ссылку на коллекцию
const collection = sc.app().pgManager().database('dbId').schema('test').collection('users')

// Синхронизация - загрузка метаданных коллекции
collection.sync().then((collection) => {
  console.log(collection.info)
})

// Создать коллекцию
const newСollection = sc.app().pgManager().database('dbId').schema('schemaName').collection('newСollection')
newСollection.create().then((collection) => {
  console.log(collection.info)
})

// Удалить коллекцию
sc.app().pgManager().database('dbId').schema('schemaName').collection('testCollection')
  .drop()
  .then((collection) => {
     console.log('Коллекция удалена')
  })

// Создать объект-ссылку на документ коллекции
const document = sc.app().pgManager().database('dbId').schema('schemaName').collection('collectionName').document('id')



// Документы (Document)

// Получить объект-ссылку на документ
const document = sc.app().pgManager().database('dbId').schema('test').collection('users').document('docId')

// Создать объект-ссылку на новый документ
const newDocument = sc.app().pgManager().database('dbId').schema('test').collection('users').document()

// Внутреннее апи документа аналогично документу публичного сервиса (см. выше)



// Запросы к БД (Query)

// Создать объект-запрос к бд
const query = sc.app().pgManager().database('dbId').schema('schemaName').collection('collectionName').query()

// Работа с запросом
query
  .from(10)                       // получить записи после 10ой
  .limit(15)                      // лимит в 15 записей
  .orderBy('name', 'ascend')      // сортировать по имени по возрастанию
  .orderBy('price', 'descend')    // сортировать по цене по убыванию
  .filterBy({                     // фильтровать опубликованные записи
    isPublished: true,
  })
  .find()                         // получить записи
  .then((items) => {
    // items - массив документов (Document)
    console.log('Items', items)
  })

• auth - сервис авторизации

const sc = require('scorocode-js-sdk')
const app = sc.initApp({ ... })

// Сервис авторизации и аутентификации пользователя
// При инициализации приложения сервис автоматически восстанавливает аутентификацию из локал стореджа
const auth = sc.app().auth()

// получить пользователя
const user = auth.currentUser // объект User

// получить информацию о пользователе
const userInfo = user.info  // объект UserInfo

// получить полномочия пользователе
const userCredentials = user.credentials // Объект ApplicationCredentials

// получить токен
const idToken = userCredentials.idToken
const accessToken = userCredentials.accessToken
const refreshToken = userCredentials.refreshToken

// Авторизировать пользователя по емеилу и паролю
auth.loginWithEmailAndPassword('user@mail.com', '123qwe').then((user) => {
  console.log('Authenticated user', user.info)
})

// Авторизировать пользователя по полномочиям
const credentials = auth.createFacebookCredentials('token...')
auth.loginWithCredentials(credentials).then((user) => {
  console.log('Authenticated user', user.info)
})

// Зарегистрировать пользователя
auth.signup('user@mail.com', '123qwe').then((user) => {
  console.log('Registered and authenticated user', user.info)
})

// Разлогинить пользователя
auth.logout().then(() => {
  console.log('User logged out')
})

// Обновить данные пользователя
user.sync().then((user) => {
  console.log('User refreshed', user.info)
})

// Обновить полномочия пользователя с помощью refreshToken
user.refreshCredentials().then((user) => {
  console.log('Credentials refreshed', user.credentials)
})

// Обновить информацию пользователя
user.firstName = 'Ivan'
user.familyName = 'Petrov'
user.update().then((user) => {
  console.log('User info updated', user.info)
})

// Удалить пользователя
user.delete().then((user) => {
  console.log('User deleted', user.uid)
})

// Прилинковать аккаунт с OpenID провайдера
const credentials = auth.createFacebookCredentials('token...')
user.linkProvider(credentials).then((providers) => {
  console.log('User account linked providers', providers)
})

// Отлинковать от пользователя аккаунт с OpenID провайдера
user.unlinkProvider('facebook').then((providers) => {
  console.log('User account linked providers', providers)
})

// events
// onAuthStateChanged - состояние аутентификации изменено (авторизован / разлогинен)
auth.on('onAuthStateChanged', (user) => {
  console.log('Current auth state', user)
})