hyper durable

Сверхпрочный

HyperDurable — это базовый класс для объектов длительного пользования, обеспечивающий естественный объектно-подобный доступ к базовому постоянному хранилищу из заглушек объектов длительного пользования. HyperDurable полностью абстрагирует API выборки устойчивых объектов, улучшая читаемость кода на уровнях бизнес-логики.

• Абстрагирует API выборки устойчивых объектов
• Автоматически сохраняет грязные данные
• Построен с использованием TypeScript
• Комплексный набор тестов

Установка

С пряжей:

yarn add @ticketbridge/hyper-durable

С НПМ:

npm i @ticketbridge/hyper-durable

Использование

Напишите свой класс долговременного объекта, расширив базовый класс HyperDurable . В конструкторе передайте state и env в HyperDurable через super() . HyperDurable загрузит все ранее сохраненные данные в память внутри своей fetch , поэтому любые свойства, которые вы установили в конструкторе после вызова super() будут переопределены любыми ранее сохраненными данными.

Внутри вашего устойчивого объекта получите доступ к свойствам и методам в памяти, используя this . Не нужно беспокоиться о постоянстве — грязные данные сохраняются в конце каждого запроса на выборку.

 // RubberDuck.js
import { HyperDurable } from '@ticketbridge/hyper-durable' ;

export class RubberDuck extends HyperDurable {
  constructor ( state , env ) {
    // Pass state and env to HyperDurable
    super ( state , env ) ;

    // Anything set here will be overriden by previously persisted data, if any exists
    // Therefore, you can safely set default values here
    this . name = 'New Duck' ;
    this . favoriteFoods = [ ] ;
  }

  addFavoriteFood ( food ) {
    this . favoriteFoods . push ( food ) ;
  }

  sayHello ( ) {
    return `Hello world, my name is ${ this . name } , and I have ${ this . favoriteFoods . length } favorite foods.` ;
  }
}

В рабочем процессе сначала проксируйте пространства имен устойчивых объектов с помощью proxyHyperDurables . Получение заглушки не изменилось: сгенерируйте свой идентификатор с помощью предпочитаемого вами метода из API пространства имен (т. е. newUniqueId , idFromName , idFromString ), затем используйте get для создания заглушки объекта.

Необходимо await каждой операции-заглушки, поскольку все они используют API-интерфейс fetch . Свойства можно прочитать прямо из заглушки. Свойства можно задать с помощью автоматически сгенерированных установщиков (в формате set + PropName ). Методы можно вызывать прямо из заглушки.

 // worker.js
import { proxyHyperDurables } from '@ticketbridge/hyper-durable' ;
import { RubberDuck } from './RubberDuck' ;

// Export the DO class
export { RubberDuck } ;

export default {
  async fetch ( request , env ) {
    // Proxy the namespace
    const { RUBBERDUCK } = proxyHyperDurables ( env , {
      // BINDINGNAME: DurableObjectClass
      RUBBERDUCK : RubberDuck
    } ) ;

    // Obtain a stub
    const id = RUBBERDUCK . idFromName ( 'firstDuck' ) ;
    const stub = RUBBERDUCK . get ( id ) ;

    // Await properties
    const name = await stub . name ; // 'New Duck'

    // Await setters
    const newName = await stub . setName ( 'Special Duck' ) ; // 'Special Duck'

    // Await methods
    await Promise . all ( [
      stub . addFavoriteFood ( 'herring' ) ,
      stub . addFavoriteFood ( 'shrimp' )
    ] ) ;
    const greeting = await stub . sayHello ( ) ; // 'Hello world, my name is Special Duck, and I have 2 favorite foods.'
  
    return new Response ( greeting ) ;
  }
} 

API

Сверхпрочный

Используйте в качестве базового класса вашего долговечного объекта. По умолчанию включает некоторые свойства и методы, которые описаны ниже.

env: Env

env передается в конструктор.

state: HyperState

state передается в конструктор плюс:

state.dirty: Set<string>

Набор свойств, которые были изменены в памяти, но еще не сохранены.

state.persisted: Set<string>

Набор свойств, которые сохраняются в хранилище устойчивых объектов.

state.tempKey: string

Используется для отслеживания ключа глубоко вложенного свойства (т. е. при доступе к this.favoriteFoods[0] state.tempKey — это favoriteFoods ).

storage: DurableObjectStorage

Хранилище объектов длительного хранения из state.storage .

router: Router

Itty-маршрутизатор для обработки входящих запросов на выборку.

async initialize()

Инициализирует загрузку, если загрузка еще не началась.

async load()

Загружает сохраненные данные в память.

async persist()

Сохраняет грязные свойства.

async destroy()

Удаляет все данные в storage , очищает state.dirty и state.persisted и удаляет все свойства из памяти.

toObject()

Возвращает все сохраненные и измененные данные как объект.

async fetch(request: Request): Promise<Response>

Инициализирует объект (если он не был инициализирован ранее), затем передает запрос router . После того как router обработает запрос, все «грязные» данные сохраняются.

proxyHyperDurables(env: Env, doBindings: { [key: string]: DOClass })

Используйте для проксирования пространств имен устойчивых объектов. Принимает два параметра: env и doBindings . env — это env вашего работника, к которому осуществляется доступ к пространствам имен. doBindings — это объект, где ключи — это имена привязок , а значения — это устойчивые классы объектов, связанные с этими привязками. Возвращает объект, где ключами являются переданные имена привязок , а значениями — связанный HyperNamespaceProxy .

Гиперпространство именПрокси

Используйте для создания идентификаторов объектов и получения заглушек объектов, как и в вышестоящем API DurableObjectNamespace.

ГиперСтаб

Создано HyperNamespaceProxy.get(id) . Доступ к методу fetch можно получить напрямую, как и в восходящем API. Заглушка также обеспечивает простой доступ к свойствам и методам.

Чтобы получить свойство, await его:

 await stub . name ;

Чтобы установить свойство, await автоматически созданного установщика (возвращает новое значение):

 await stub . setName ( 'Eendje' ) ;

Чтобы вызвать метод, await его ( ПРИМЕЧАНИЕ. Если метод не имеет возвращаемого значения, он вернет значение null вместо обычного undefined ):

 await stub . sayHello ( ) ;

Свойства и методы заглушки вернут свое значение непосредственно в случае успеха. Если операция завершится неудачно, будет выдано сообщение HyperError следующей структуры:

 {
  message : 'Error message' ,
  details : 'Error details'
} 

Особая благодарность

Эта библиотека была вдохновлена ​​книгой itty-durable от Кевина Уитли.