hyper durable

HyperDurable

HyperDurable ist eine Basisklasse für Durable Objects, um einen natürlichen, objektähnlichen Zugriff auf den zugrunde liegenden persistenten Speicher von Durable Object Stubs aus zu ermöglichen. HyperDurable abstrahiert die Abruf-API für dauerhafte Objekte vollständig und verbessert so die Lesbarkeit des Codes in Geschäftslogikschichten.

• Abstrahiert die API zum Abruf dauerhafter Objekte
• Behält schmutzige Daten automatisch bei
• Mit TypeScript erstellt
• Umfangreiche Testsuite

Installation

Mit Garn:

yarn add @ticketbridge/hyper-durable

Mit NPM:

npm i @ticketbridge/hyper-durable

Verwendung

Schreiben Sie Ihre dauerhafte Objektklasse, indem Sie die HyperDurable Basisklasse erweitern. Übergeben Sie im Konstruktor den state und env über super() an HyperDurable . HyperDurable lädt alle zuvor gespeicherten Daten innerhalb seines fetch in den Speicher, sodass alle Eigenschaften, die Sie im Konstruktor nach dem Aufruf von super() festlegen, durch alle zuvor gespeicherten Daten überschrieben werden.

Greifen Sie innerhalb Ihres dauerhaften Objekts this auf Eigenschaften und Methoden im Speicher zu. Sie müssen sich keine Gedanken über die Persistenz machen – fehlerhafte Daten bleiben am Ende jeder Abrufanforderung bestehen.

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

Stellen Sie in Ihrem Worker zunächst einen Proxy für Ihre dauerhaften Objekt-Namespaces mit proxyHyperDurables her. Das Erhalten eines Stubs ist unverändert: Generieren Sie Ihre ID mit Ihrer bevorzugten Methode aus der Namespace-API (z. B. newUniqueId , idFromName , idFromString ) und verwenden Sie dann get , um einen Objekt-Stub zu erstellen.

Jede Stub-Operation muss await werden, da sie alle die fetch -API unter der Haube verwenden. Eigenschaften können direkt aus dem Stub gelesen werden. Eigenschaften können mit ihren automatisch generierten Settern festgelegt werden (im Format set + PropName ). Methoden können direkt aus dem Stub aufgerufen werden.

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

HyperDurable

Verwenden Sie es als Basisklasse Ihres dauerhaften Objekts. Enthält standardmäßig einige Eigenschaften und Methoden, die unten beschrieben werden.

env: Env

Die im Konstruktor env Umgebung.

state: HyperState

Der im Konstruktor übergebene state , plus:

state.dirty: Set<string>

Satz von Eigenschaften, die im Speicher geändert wurden, aber noch nicht beibehalten werden.

state.persisted: Set<string>

Satz von Eigenschaften, die im dauerhaften Objektspeicher beibehalten werden.

state.tempKey: string

Wird verwendet, um den Schlüssel einer tief verschachtelten Eigenschaft zu verfolgen (d. h. beim Zugriff auf this.favoriteFoods[0] ist state.tempKey favoriteFoods ).

storage: DurableObjectStorage

Dauerhafter Objektspeicher von state.storage .

router: Router

Ein Itty-Router zur Verarbeitung eingehender Abrufanforderungen.

async initialize()

Initialisiert den Ladevorgang, wenn der Ladevorgang noch nicht begonnen hat.

async load()

Lädt persistente Daten in den Speicher.

async persist()

Behält schmutzige Eigenschaften bei.

async destroy()

Löscht alle Daten im storage , löscht state.dirty und state.persisted und löscht alle Eigenschaften aus dem Speicher.

toObject()

Gibt alle persistenten und fehlerhaften Daten als Objekt zurück.

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

Initialisiert das Objekt (sofern es nicht zuvor initialisiert wurde) und leitet dann die Anforderung an router weiter. Nachdem router die Anfrage verarbeitet hat, bleiben alle fehlerhaften Daten bestehen.

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

Verwenden Sie diese Option, um Ihre dauerhaften Objekt-Namespaces als Proxy zu verwenden. Akzeptiert zwei Parameter: env und doBindings . env ist die env Ihres Workers, in der auf Namespaces zugegriffen wird. doBindings ist ein Objekt, bei dem die Schlüssel Bindungsnamen und die Werte die dauerhaften Objektklassen sind, die diesen Bindungen zugeordnet sind. Gibt ein Objekt zurück, bei dem die Schlüssel die übergebenen Bindungsnamen und die Werte der zugehörige HyperNamespaceProxy sind.

HyperNamespaceProxy

Wird verwendet, um Objekt-IDs zu generieren und Objekt-Stubs abzurufen, genau wie in der Upstream-DurableObjectNamespace-API.

HyperStub

Erstellt von HyperNamespaceProxy.get(id) . Auf die fetch -Methode kann wie in der Upstream-API direkt zugegriffen werden. Der Stub ermöglicht außerdem den einfachen Zugriff auf Eigenschaften und Methoden.

Um eine Immobilie zu erhalten, await darauf:

 await stub . name ;

Um eine Eigenschaft festzulegen, await den automatisch generierten Setter (gibt den neuen Wert zurück):

 await stub . setName ( 'Eendje' ) ;

Um eine Methode aufzurufen, await darauf ( HINWEIS: Wenn eine Methode keinen Rückgabewert hat, gibt sie null anstelle des üblichen undefined zurück):

 await stub . sayHello ( ) ;

Stub-Eigenschaften und -Methoden geben im Erfolgsfall ihren Wert direkt zurück. Wenn der Vorgang fehlschlägt, wird ein HyperError mit der folgenden Struktur ausgelöst:

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

Besonderer Dank

Diese Bibliothek wurde stark von itty-durable von Kevin Whitley inspiriert.