dyngoose
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.2 • Public • Published

    Build Status npm version Semantic Release enabled Dependabot Status

    Dyngoose

    Elegant DynamoDB object modeling for Typescript.

    Let's face it, all good databases need good model casting. DynamoDB is powerful but libraries that used it were not. That's where Dyngoose comes in.

    Getting Started

    Take a look the docs! to find information about how to get started.

    Features

    1. Cast your tables, attributes, and indexes using TypeScript classes.
    2. Generate your CloudFormation templates based on your code, or perform your table operations on demand; see Deployment.
    3. Intelligent and powerful querying syntax, see Querying and MagicSearch.
    4. Selectively update item attributes, prevents wasteful uploading of unchanged values.
    5. Data serialization, cast any JavaScript value into a DynamoDB attribute value.
    6. DynamoDB Accelerator (DAX) and Amazon X-Ray support, see Connections.
    7. Optimizes connection to DynamoDB HTTP service using Keep-Alive, see code segment.
    8. Incredibly easy local development, with support for seeding a local database.
    9. Supports conditional writes, see Saving.

    Example Usage

    import { Dyngoose } from 'dyngoose'
    
    @Dyngoose.$Table({ name: 'Card' })
    class Card extends Dyngoose.Table {
      @Dyngoose.Attribute.Number()
      public id: number
    
      @Dyngoose.Attribute.String()
      public title: string
    
      @Dyngoose.Attribute.Number()
      public number: number
    
      @Dyngoose.Attribute.Date({ timeToLive: true })
      public expiresAt: Date
    
      @Dyngoose.$PrimaryKey('id', 'title')
      static readonly primaryKey: Dyngoose.Query.PrimaryKey<Card, number, string>
    
      @Dyngoose.$DocumentClient()
      static readonly documentClient: Dyngoose.DocumentClient<Card>
    }
    
    // Perform table operations
    await Card.createTable()
    await Card.deleteTable()
    
    // Creating records
    const card = new Card()
    card.id = 100
    card.title = 'Title'
    
    // note: Card.new is correct, this is a custom method that allows for a strongly-typed object
    const card2 = Card.new({
      id: 100,
      title: 'Title'
    })
    
    // Save a record
    await card.save()
    
    // Batch Put
    await Card.documentClient.batchPut([
      Card.new(),
      Card.new()
    ])
    
    // Get record by the primary key
    await Card.primaryKey.get({ id: 100, title: 'Title' })
    
    // BatchGet
    // This array is strongly typed such as Array<[number, string]> so don't worry.
    await Card.primaryKey.batchGet([
      [100, 'Title'],
      [200, 'Title2']
    ])
    
    // Searching and Advanced Querying
    // Your values will be strictly typed based on the attribute being filtered
    await Card.search()
      .filter('id').eq(100)
      .filter('title').gte('Title')
      .exec()
    
    // Easily delete record
    await card.delete()
    
    // Query
    // Queries are always strongly typed. (['>=', T] | ['=', T] ...)
    const cards = await Card.primaryKey.query({
      id: 100,
      title: ['>=', 'Title']
    })
    
    // you can loop through outputs, which is a native JavaScript array
    for (const card of cards) {
      console.log(card.id, card.title)
    }
    
    // the output contains additional properties
    console.log(`Your query returned ${cards.count} and scanned ${cards.scannedCount} documents`)
    
    // Atomic counters, advanced update expressions
    // Increment or decrement automatically, based on the current value in DynamoDB
    card.set('number', 2, { operator: 'increment' }) // if the current value had been 5, it would now be 7
    card.set('number', 2, { operator: 'decrement' }) // if the current value had been 5, it would now be 3

    TS Compiler Setting

    Dyngoose utilizes TypeScript decorators, to use them you must enable them within your tsconfig.json file:

    {
        "compilerOptions": {
            // other options…
            //
            "experimentalDecorators": true, // required
            "emitDecoratorMetadata": true // required
        }
    }

    Honorable mentions

    I originally based a lot of of this work on Dynamoose, reworking it for TypeScript and adding adding better querying logic. About two years later, I pulled in some work from dynamo-types and reworked it further to make what has become Dyngoose. I want to thank the creators and all the people who worked on both of those projects.

    Install

    npm i dyngoose

    DownloadsWeekly Downloads

    7,923

    Version

    3.0.2

    License

    ISC

    Unpacked Size

    762 kB

    Total Files

    363

    Last publish

    Collaborators

    • benhutchins