hyper durable

Hiperdurable

HyperDurable es una clase base para Durable Objects que permite el acceso natural, similar a un objeto, al almacenamiento persistente subyacente desde los resguardos de Durable Object. HyperDurable abstrae completamente la API de recuperación de objetos duraderos, lo que mejora la legibilidad del código en las capas de lógica empresarial.

• Resume la API de recuperación de objetos duraderos
• Persiste automáticamente los datos sucios
• Construido con TypeScript
• Conjunto de pruebas completo

Instalación

Con hilo:

yarn add @ticketbridge/hyper-durable

Con el MNP:

npm i @ticketbridge/hyper-durable

Uso

Escriba su clase de objeto duradero extendiendo la clase base HyperDurable . En el constructor, pase el state y env a HyperDurable mediante super() . HyperDurable cargará todos los datos previamente persistentes en la memoria dentro de su fetch , por lo que cualquier propiedad que establezca en el constructor después de llamar super() será anulada por cualquier dato previamente persistente.

Dentro de su objeto duradero, acceda a las propiedades y métodos en la memoria usando this . No hay necesidad de preocuparse por la persistencia: los datos sucios persisten al final de cada solicitud de recuperación.

 // 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.` ;
  }
}

En su trabajador, primero represente sus espacios de nombres de objetos duraderos con proxyHyperDurables . La obtención de un código auxiliar no cambia: genere su identificación con su método preferido desde la API del espacio de nombres (es decir, newUniqueId , idFromName , idFromString ), luego use get para construir un código auxiliar de objeto.

Se debe await cada operación de código auxiliar, ya que todas usan la API fetch interna. Las propiedades se pueden leer directamente desde el código auxiliar. Las propiedades se pueden configurar con sus configuradores generados automáticamente (en el formato set + PropName ). Los métodos se pueden llamar directamente desde el código auxiliar.

 // 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

Hiperdurable

Úselo como clase base de su objeto duradero. Incluye algunas propiedades y métodos de forma predeterminada, que se describen a continuación.

env: Env

El env pasado en el constructor.

state: HyperState

El state pasado en el constructor, más:

state.dirty: Set<string>

Conjunto de propiedades que se han modificado en la memoria pero que aún no persisten.

state.persisted: Set<string>

Conjunto de propiedades que persisten en el almacenamiento de objetos duraderos.

state.tempKey: string

Se utiliza para rastrear la clave de una propiedad profundamente anidada (es decir, al acceder a this.favoriteFoods[0] , state.tempKey es favoriteFoods ).

storage: DurableObjectStorage

Almacenamiento de objetos duradero, de state.storage .

router: Router

Un enrutador itty para manejar solicitudes de recuperación entrantes.

async initialize()

Inicializa la carga si la carga aún no ha comenzado.

async load()

Carga datos persistentes en la memoria.

async persist()

Persiste propiedades sucias.

async destroy()

Elimina todos los datos storage , borra state.dirty y state.persisted y elimina todas las propiedades de la memoria.

toObject()

Devuelve todos los datos persistentes y sucios como un objeto.

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

Inicializa el objeto (si no se ha inicializado previamente) y luego pasa la solicitud al router . Después de que router maneja la solicitud, los datos sucios persisten.

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

Úselo para representar sus espacios de nombres de objetos duraderos. Acepta dos parámetros: env y doBindings . env es el env de su trabajador donde se accede a los espacios de nombres. doBindings es un objeto, donde las claves son nombres de enlace y los valores son las clases de objetos duraderos asociados con esos enlaces. Devuelve un objeto, donde las claves son los nombres de enlace pasados ​​y los valores son el HyperNamespaceProxy asociado.

HyperNamespaceProxy

Úselo para generar ID de objetos y obtener resguardos de objetos, tal como en la API DurableObjectNamespace ascendente.

hiperstub

Producido por HyperNamespaceProxy.get(id) . Se puede acceder al método fetch directamente, como en la API ascendente. El código auxiliar también permite un acceso sencillo a propiedades y métodos.

Para conseguir una propiedad, await :

 await stub . name ;

Para establecer una propiedad, await al definidor generado automáticamente (devuelve el nuevo valor):

 await stub . setName ( 'Eendje' ) ;

Para invocar un método, await ( NOTA: si un método no tiene valor de retorno, devolverá null en lugar del habitual undefined ):

 await stub . sayHello ( ) ;

Las propiedades y métodos de código auxiliar devolverán su valor directamente en caso de éxito. Si la operación falla, se generará un HyperError con la siguiente estructura:

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

agradecimiento especial

Esta biblioteca se inspiró en gran medida en itty-duradero de Kevin Whitley.