[Beyonce]: Support inverted indexes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ginger.io/beyonce",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "Type-safe DynamoDB query builder for TypeScript. Designed with single-table architecture in mind.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/main/codegen/generateGSIs.ts

@@ -31,7 +31,7 @@ function generateGSIsForTable(table: Table): string {
     const sk = sortKey.replace("$", "")
     const models = fieldToModels[pk].map((_) => `${_}Model`).join(", ")
 
-    return `const ${name}GSI = ${table.name}Table.gsi("${name}")
+    return `export const ${name}GSI = ${table.name}Table.gsi("${name}")
       .models([${models}])
       .partitionKey("${pk}")
       .sortKey("${sk}")

src/main/dynamo/Beyonce.ts

@@ -39,7 +39,11 @@ export class Beyonce {
   private jayz?: JayZ
   private consistentReads: boolean
 
-  constructor(private table: Table, dynamo: DynamoDB, options: Options = {}) {
+  constructor(
+    private table: Table<string, string>,
+    dynamo: DynamoDB,
+    options: Options = {}
+  ) {
     this.client = new DynamoDB.DocumentClient({ service: dynamo })
 
     if (options.jayz !== undefined) {

src/main/dynamo/GSI.ts

@@ -5,11 +5,15 @@ import { ExtractFields } from "./types"
 
 type StringKey<T> = keyof ExtractFields<T> & string
 
-export class GSI<T extends Model<any, any, any>> {
+export class GSI<
+  PK extends string,
+  SK extends string,
+  T extends Model<any, any, any>
+> {
   private modelTags: string[]
 
   constructor(
-    private table: Table,
+    private table: Table<PK, SK>,
     readonly name: string,
     private models: T[],
     private partitionKeyName: StringKey<T>,
@@ -25,29 +29,35 @@ export class GSI<T extends Model<any, any, any>> {
   }
 }
 
-export class GSIBuilder {
-  constructor(private table: Table, private name: string) {}
+export class GSIBuilder<PK extends string, SK extends string> {
+  constructor(private table: Table<PK, SK>, private name: string) {}
 
-  models<T extends Model<any, any, any>>(models: T[]) {
+  models<T extends Model<any, any, any>>(
+    models: T[]
+  ): GSIKeyBuilder<PK, SK, T> {
     return new GSIKeyBuilder(this.table, this.name, models)
   }
 }
 
-class GSIKeyBuilder<T extends Model<any, any, any>> {
+class GSIKeyBuilder<
+  PK extends string,
+  SK extends string,
+  T extends Model<any, any, any>
+> {
   private partitionKeyName?: StringKey<T>
 
   constructor(
-    private table: Table,
+    private table: Table<PK, SK>,
     private name: string,
     private models: T[]
   ) {}
 
-  partitionKey(partitionKeyName: StringKey<T>): this {
+  partitionKey(partitionKeyName: PK | SK | StringKey<T>): this {
     this.partitionKeyName = partitionKeyName
     return this
   }
 
-  sortKey(sortKeyName: StringKey<T>): GSI<T> {
+  sortKey(sortKeyName: PK | SK | StringKey<T>): GSI<PK, SK, T> {
     return new GSI(
       this.table,
       this.name,

src/main/dynamo/QueryBuilder.ts

@@ -1,8 +1,8 @@
 import { JayZ } from "@ginger.io/jay-z"
 import { DynamoDB } from "aws-sdk"
+import { QueryExpressionBuilder } from "./expressions/QueryExpressionBuilder"
 import { groupModelsByType } from "./groupModelsByType"
 import { PartitionKey, PartitionKeyAndSortKeyPrefix } from "./keys"
-import { QueryExpressionBuilder } from "./expressions/QueryExpressionBuilder"
 import { Table } from "./Table"
 import { GroupedModels, TaggedModel } from "./types"
 import { decryptOrPassThroughItem, toJSON } from "./util"

src/main/dynamo/Table.ts

@@ -3,16 +3,16 @@ import { Model, PartitionKeyBuilder } from "./Model"
 import { Partition } from "./Partition"
 import { TaggedModel } from "./types"
 
-export class Table {
+export class Table<PK extends string = string, SK extends string = string> {
   readonly tableName: string
-  readonly partitionKeyName: string
-  readonly sortKeyName: string
+  readonly partitionKeyName: PK
+  readonly sortKeyName: SK
   private encryptionBlacklist: Set<string>
 
   constructor(config: {
     name: string
-    partitionKeyName: string
-    sortKeyName: string
+    partitionKeyName: PK
+    sortKeyName: SK
     encryptionBlacklist?: string[]
   }) {
     this.tableName = config.name
@@ -38,7 +38,7 @@ export class Table {
     return new Partition(models)
   }
 
-  gsi(name: string): GSIBuilder {
+  gsi(name: string): GSIBuilder<PK, SK> {
     return new GSIBuilder(this, name)
   }
 

src/test/codegen/generateCode.test.ts

@@ -233,7 +233,8 @@ Tables:
         sortKey: $id
 `)
 
-  expect(result).toContain(`const modelByIdGSI = LibraryTable.gsi("modelById")
+  expect(result)
+    .toContain(`export const modelByIdGSI = LibraryTable.gsi("modelById")
   .models([AuthorModel, BookModel])
   .partitionKey("model")
   .sortKey("id")

src/test/dynamo/Beyonce.test.ts

@@ -5,7 +5,7 @@ import { Beyonce } from "../../main/dynamo/Beyonce"
 import {
   aMusicianWithTwoSongs,
   byModelAndIdGSI,
-  byNameAndIdGSI,
+  invertedIndexGSI,
   ModelType,
   MusicianModel,
   MusicianPartition,
@@ -195,8 +195,8 @@ describe("Beyonce", () => {
     await testGSIByModel()
   })
 
-  it("should query GSI by name", async () => {
-    await testGSIByName()
+  it("should query inverted index GSI", async () => {
+    await testInvertedIndexGSI()
   })
 
   it("should write multiple items at once", async () => {
@@ -275,9 +275,9 @@ describe("Beyonce", () => {
     await testGSIByModel(jayZ)
   })
 
-  it("should query GSI by name with jayZ", async () => {
+  it("should query inverted index GSI by name with jayZ", async () => {
     const jayZ = await createJayZ()
-    await testGSIByName(jayZ)
+    await testInvertedIndexGSI(jayZ)
   })
 
   it("should write multiple items at once with jayZ", async () => {
@@ -545,16 +545,53 @@ async function testGSIByModel(jayZ?: JayZ) {
   expect(result).toEqual({ musician: [], song: [song1, song2] })
 }
 
-async function testGSIByName(jayZ?: JayZ) {
+async function testInvertedIndexGSI(jayZ?: JayZ) {
   const db = await setup(jayZ)
-  const [musician, song1, song2] = aMusicianWithTwoSongs()
-  await Promise.all([db.put(musician), db.put(song1), db.put(song2)])
 
-  const result = await db
-    .queryGSI(byNameAndIdGSI.name, byNameAndIdGSI.key(musician.name))
+  const santana = MusicianModel.create({
+    id: "1",
+    name: "Santana",
+    details: {
+      description: "famous guitarist",
+    },
+  })
+
+  const slash = MusicianModel.create({
+    id: "2",
+    name: "Slash",
+    details: {
+      description: "another famous guitarist",
+    },
+  })
+
+  const santanasSong = SongModel.create({
+    musicianId: santana.id,
+    id: "1",
+    title: "A song where Slash and Santana play together",
+    mp3: Buffer.from("fake-data", "utf8"),
+  })
+
+  const slashesSong = SongModel.create({
+    musicianId: slash.id,
+    id: "1", // note the same id as above
+    title: "A song where Slash and Santana play together",
+    mp3: Buffer.from("fake-data", "utf8"),
+  })
+
+  await db.batchPutWithTransaction({
+    items: [santana, slash, santanasSong, slashesSong],
+  })
+
+  // Now when we query our inverted index, pk and sk are reversed,
+  // so song id: 1 => [santanasSong, slashesSong]
+  const { song: songs } = await db
+    .queryGSI(
+      invertedIndexGSI.name,
+      invertedIndexGSI.key(`${ModelType.Song}-1`)
+    )
     .exec()
 
-  expect(result).toEqual({ musician: [musician] })
+  expect(songs).toEqual([santanasSong, slashesSong])
 }
 
 async function testBatchWriteWithTransaction(jayZ?: JayZ) {

src/test/dynamo/models.ts

@@ -46,11 +46,11 @@ export const byModelAndIdGSI = table
   .partitionKey("model")
   .sortKey("id")
 
-export const byNameAndIdGSI = table
-  .gsi("byNameAndId")
-  .models([MusicianModel])
-  .partitionKey("name")
-  .sortKey("id")
+export const invertedIndexGSI = table
+  .gsi("invertedIndex")
+  .models([MusicianModel, SongModel])
+  .partitionKey("sk")
+  .sortKey("pk")
 
 export function aMusicianWithTwoSongs(): [Musician, Song, Song] {
   const musician = MusicianModel.create({

src/test/dynamo/util.ts

@@ -43,10 +43,10 @@ export async function setup(jayz?: JayZ): Promise<Beyonce> {
 
       GlobalSecondaryIndexes: [
         {
-          IndexName: "byNameAndId",
+          IndexName: "invertedIndex",
           KeySchema: [
-            { AttributeName: "name", KeyType: "HASH" },
-            { AttributeName: "id", KeyType: "RANGE" },
+            { AttributeName: "sk", KeyType: "HASH" },
+            { AttributeName: "pk", KeyType: "RANGE" },
           ],
           Projection: {
             ProjectionType: "ALL",