feat: Add upsertOne() to db model driver

Author: codinsonn

features/@app-core/models/Settings.model.ts

@@ -1,5 +1,5 @@
 import { z, schema } from '@green-stack/schemas'
-import { createSchemaModel } from '@db/driver'
+import { createSchemaModel, validateDriverModel } from '@db/driver'
 
 /* --- Schema ---------------------------------------------------------------------------------- */
 
@@ -18,4 +18,4 @@ export const SettingsModel = createSchemaModel(Setting)
 
 /* --- Drivers --------------------------------------------------------------------------------- */
 
-export const driverModel = SettingsModel.driver
+export const driverModel = validateDriverModel(SettingsModel.driver)

packages/@db-driver/index.ts

@@ -12,3 +12,4 @@ export const createSchemaModel = dbDriver['createSchemaModel']
 /* --- Export Driver Helpers ------------------------------------------------------------------- */
 
 export { validateDriver } from './utils/validateDriver.db'
+export { validateDriverModel } from './utils/validateDriverModel.db'

packages/@db-driver/scripts/collect-models.ts

@@ -51,7 +51,7 @@ const collectModels = () => {
 
             // Skip if not a valid model
             const modelFileContents = fs.readFileSync(modelFilePath, 'utf-8')
-            const isValidModel = modelFileContents.includes('export const driverModel = ')
+            const isValidModel = modelFileContents.includes('export const driverModel = validateDriverModel(')
             if (!isValidModel) return acc
 
             // Figure out model workspace from filename

packages/@db-driver/utils/createSchemaModel.mock.test.ts

@@ -62,7 +62,7 @@ test('createSchemaModel() creates a new schema model with DB driver methods atta
 })
 
 test('Model.driver.insertOne() inserts a new record in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User1')
+    const UserModel = createSchemaModel(UserSchema, 'UserInsertOne1')
     const newUser = await UserModel.driver.insertOne({
         name: 'Thorr',
         email: 'thorr@codinsonn.dev',
@@ -74,7 +74,7 @@ test('Model.driver.insertOne() inserts a new record in memory', async () => {
 })
 
 test('Model.driver.insertOne() throws if inserted record does not match schema', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User2')
+    const UserModel = createSchemaModel(UserSchema, 'UserInsertOne2')
     // Check that we throw an error when inserting a record with invalid data
     await expect(UserModel.driver.insertOne({})).rejects.toThrow() // Missing required fields
     await expect(UserModel.driver.insertOne({ name: 'Thorr' })).rejects.toThrow() // Missing required field email
@@ -83,7 +83,7 @@ test('Model.driver.insertOne() throws if inserted record does not match schema',
 })
 
 test('Model.driver.insertMany() inserts multiple records in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User3')
+    const UserModel = createSchemaModel(UserSchema, 'UserInsertMany1')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -107,7 +107,7 @@ test('Model.driver.insertMany() inserts multiple records in memory', async () =>
 })
 
 test('Model.driver.insertMany() throws if inserted records do not match schema', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User4')
+    const UserModel = createSchemaModel(UserSchema, 'UserInsertMany2')
     // Check that we throw an error when inserting records with invalid data
     await expect(UserModel.driver.insertMany([{}])).rejects.toThrow() // Missing required fields
     await expect(UserModel.driver.insertMany([{ name: 'Thorr' }])).rejects.toThrow() // Missing required field email
@@ -116,7 +116,7 @@ test('Model.driver.insertMany() throws if inserted records do not match schema',
 })
 
 test('Model.driver.findOne() finds a record stored in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User5')
+    const UserModel = createSchemaModel(UserSchema, 'UserFindOne1')
     const newUser = await UserModel.driver.insertOne({
         name: 'Thorr',
         email: 'thorr@codinsonn.dev',
@@ -145,7 +145,7 @@ test('Model.driver.findOne() finds a record stored in memory', async () => {
 })
 
 test('Model.driver.findMany() finds multiple records stored in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User6')
+    const UserModel = createSchemaModel(UserSchema, 'UserFindMany1')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -168,7 +168,7 @@ test('Model.driver.findMany() finds multiple records stored in memory', async ()
 })
 
 test('Model.driver.updateOne() updates a record stored in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User7')
+    const UserModel = createSchemaModel(UserSchema, 'UserUpdateOne1')
     const newUser = await UserModel.driver.insertOne({
         name: 'Thorr',
         email: 'thorr@codinsonn.dev',
@@ -183,7 +183,7 @@ test('Model.driver.updateOne() updates a record stored in memory', async () => {
 })
 
 test('Model.driver.updateOne() with errorOnUnmatched: true throws if updated record does not match schema', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User8')
+    const UserModel = createSchemaModel(UserSchema, 'UserUpdateOne2')
     const newUser = await UserModel.driver.insertOne({
         name: 'Thorr',
         email: 'thorr@codinsonn.dev',
@@ -202,7 +202,7 @@ test('Model.driver.updateOne() with errorOnUnmatched: true throws if updated rec
 })
 
 test('Model.driver.updateMany() updates multiple records stored in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User9')
+    const UserModel = createSchemaModel(UserSchema, 'UserUpdateMany1')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -223,7 +223,7 @@ test('Model.driver.updateMany() updates multiple records stored in memory', asyn
 })
 
 test('Model.driver.updateMany() with errorOnUnmatched: true throws if updated records do not match schema', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User10')
+    const UserModel = createSchemaModel(UserSchema, 'UserUpdateMany2')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -246,8 +246,59 @@ test('Model.driver.updateMany() with errorOnUnmatched: true throws if updated re
     await expect(() => UserModel.driver.updateMany({ email: '' }, { name: 'Thorr' })).not.toThrow()
 })
 
+test('Model.driver.upsertOne() inserts a new record if it does not exist', async () => {
+    const UserModel = createSchemaModel(UserSchema, 'UserUpsertOne1')
+    // Check that we can insert a new record
+    const newUser = await UserModel.driver.upsertOne({
+        name: 'Thorr',
+    }, {
+        name: 'Thorr',
+        email: 'thorr@codinsonn.dev',
+    })
+    // Check that the record was inserted
+    expect(newUser).toBeDefined()
+    expect(newUser.id).toBeDefined()
+    expect(newUser.name).toBe('Thorr')
+    expect(newUser.email).toBe('thorr@codinsonn.dev')
+    // Check that we can find the record by id
+    const foundById = await UserModel.driver.findOne({ id: newUser.id })
+    expect(foundById).toBeDefined()
+    expect(foundById.id).toBe(newUser.id)
+    expect(foundById.name).toBe('Thorr')
+    expect(foundById.email).toBe('thorr@codinsonn.dev')
+})
+
+test('Model.driver.upsertOne() updates an existing record if it exists', async () => {
+    const UserModel = createSchemaModel(UserSchema, 'UserUpsertOne2')
+    const onlyUser = await UserModel.driver.insertOne({
+        name: 'Thorr',
+        email: 'thorr@codinsonn.dev',
+    })
+    // Check that we can update an existing record
+    const updatedUser = await UserModel.driver.upsertOne({
+        name: 'Thorr',
+    }, {
+        name: 'Thorr',
+        email: 'thorr@fullproduct.dev',
+    })
+    // Check that the record was updated
+    expect(updatedUser).toBeDefined()
+    expect(updatedUser.id).toBe(onlyUser.id)
+    expect(updatedUser.name).toBe('Thorr')
+    expect(updatedUser.email).toBe('thorr@fullproduct.dev')
+    // Check that we can find the record by id
+    const foundById = await UserModel.driver.findOne({ id: onlyUser.id })
+    expect(foundById).toBeDefined()
+    expect(foundById.id).toBe(onlyUser.id)
+    expect(foundById.name).toBe('Thorr')
+    expect(foundById.email).toBe('thorr@fullproduct.dev')
+    // Check that we can no longer find the record by the old email
+    const notFoundByEmail = await UserModel.driver.findOne({ email: 'thorr@codinsonn.dev' })
+    expect(notFoundByEmail).toBeUndefined()
+})
+
 test('Model.driver.deleteOne() deletes a record stored in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User11')
+    const UserModel = createSchemaModel(UserSchema, 'UserDeleteOne1')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -275,7 +326,7 @@ test('Model.driver.deleteOne() deletes a record stored in memory', async () => {
 })
 
 test('Model.driver.deleteMany() deletes multiple records stored in memory', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User12')
+    const UserModel = createSchemaModel(UserSchema, 'UserDeleteMany1')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -301,7 +352,7 @@ test('Model.driver.deleteMany() deletes multiple records stored in memory', asyn
 })
 
 test('Model.driver.deleteMany() returns an empty array by default if no records are found', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User13')
+    const UserModel = createSchemaModel(UserSchema, 'UserDeleteMany2')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -319,7 +370,7 @@ test('Model.driver.deleteMany() returns an empty array by default if no records
 })
 
 test('Model query filters support logical $and, $or, $nor & $not operators', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User14')
+    const UserModel = createSchemaModel(UserSchema, 'UserQueryFilters1')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -364,7 +415,7 @@ test('Model query filters support logical $and, $or, $nor & $not operators', asy
 })
 
 test('Model query filters support conditional field operators $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin', async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User15')
+    const UserModel = createSchemaModel(UserSchema, 'UserQueryFilters2')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',
@@ -446,7 +497,7 @@ test('Model query filters support conditional field operators $eq, $ne, $gt, $gt
 })
 
 test("Model query filters support nested fields", async () => {
-    const UserModel = createSchemaModel(UserSchema, 'User16')
+    const UserModel = createSchemaModel(UserSchema, 'UserQueryFilters3')
     const newUsers = await UserModel.driver.insertMany([
         {
             name: 'Thorr',

packages/@db-driver/utils/createSchemaModel.mock.ts

@@ -284,6 +284,25 @@ export const createSchemaModel = <
         }
     }
 
+    /** --- upsertOne() ------------------------------------------------------------------------ */
+    /** -i- Updates or inserts a single record in the collection */
+    const upsertOne = async (query: QueryFilter, record: Partial<DataType>) => {
+        memoryDB[modelKey] = memoryDB[modelKey] || {}
+        try {
+            // Find the record to update
+            const recordToUpdate = await findOne(query) as DataType
+            if (recordToUpdate) {
+                // Update the record
+                return updateOne(query, record as Prettify<Partial<Omit<DataType, 'id'>>>, true)
+            } else {
+                // Insert the record
+                return insertOne(record)
+            }
+        } catch (error: any$FixMe) {
+            throw new Error(`Failed to upsert record in "${modelKey}" collection: ${error.message}`)
+        }
+    }
+
     /** --- deleteOne() ------------------------------------------------------------------------ */
     /** -i- Removes a single record from the collection */
     const deleteOne = async (query: QueryFilter, errorOnUnmatched = false) => {
@@ -340,6 +359,8 @@ export const createSchemaModel = <
         update: updateOne,
         updateOne,
         updateMany,
+        upsertOne,
+        upsert: upsertOne,
         delete: deleteOne,
         deleteOne,
         deleteMany,

packages/@db-driver/utils/validateDriverModel.db.ts

@@ -0,0 +1,26 @@
+import { z } from '@green-stack/schemas'
+
+/* --- Schema ---------------------------------------------------------------------------------- */
+
+export const DbDriverModelSchema = z.object({
+    insertOne: z.function().args(z.any()).returns(z.promise(z.any())),
+    insertMany: z.function().args(z.array(z.any())).returns(z.promise(z.array(z.any()))),
+    findOne: z.function().args(z.any()).returns(z.promise(z.any())),
+    findMany: z.function().args(z.any()).returns(z.promise(z.array(z.any()))),
+    updateOne: z.function().args(z.any(), z.any(), z.boolean().optional()).returns(z.promise(z.any())),
+    updateMany: z.function().args(z.any(), z.any(), z.boolean().optional()).returns(z.promise(z.array(z.any()))),
+    upsertOne: z.function().args(z.any(), z.any()).returns(z.promise(z.any())),
+    deleteOne: z.function().args(z.any(), z.boolean().optional()).returns(z.promise(z.any())),
+    deleteMany: z.function().args(z.any(), z.boolean().optional()).returns(z.promise(z.array(z.any()))),
+})
+
+/* --- Types ----------------------------------------------------------------------------------- */
+
+export type DbModelShape = z.infer<typeof DbDriverModelSchema>
+
+/** --- validateDriverModel() ----------------------------------------------------------------------- */
+/** -i- Validates whether a DB model matches the expected methods */
+export const validateDriverModel = <DB_MODEL extends DbModelShape>(model: DB_MODEL) => {
+    DbDriverModelSchema.parse(model)
+    return model
+}

packages/@green-stack-core/schemas/index.ts

@@ -122,19 +122,38 @@ declare module 'zod' {
         Input = z.objectInputType<T, Catchall, UnknownKeys>
     > {
         nameSchema(name: string): this
+
         extendSchema<S extends z.ZodRawShape>(name: string, shape: S): ZodObject<T & S, UnknownKeys, Catchall>
+        
         pickSchema<Mask extends z.util.Exactly<{ [k in keyof T]?: true; }, Mask>>(
             schemaName: string,
             mask: Mask
         ): z.ZodObject<Pick<T, Extract<keyof T, keyof Mask>>, UnknownKeys, Catchall>
+
         omitSchema<Mask extends z.util.Exactly<{ [k in keyof T]?: true; }, Mask>>(
             schemaName: string,
             mask: Mask
         ): z.ZodObject<Omit<T, keyof Mask>, UnknownKeys, Catchall>
+
         applyDefaults<D extends Record<string, unknown> = Record<string, unknown>>(
             data: D,
             logErrors?: boolean
         ): D & Output
+
+        // -- Deprecations --
+
+        /** @deprecated Use `.extendSchema('NewName', { ...shape })` instead */
+        extend<S extends z.ZodRawShape>(shape: S): ZodObject<T & S, UnknownKeys, Catchall>
+
+        /** @deprecated Use `.pickSchema('NewName', { ...mask })` instead */
+        pick<Mask extends z.util.Exactly<{ [k in keyof T]?: true; }, Mask>>(
+            mask: Mask
+        ): z.ZodObject<Pick<T, Extract<keyof T, keyof Mask>>, UnknownKeys, Catchall>
+
+        /** @deprecated Use `.omitSchema('NewName', { ...mask })` instead */
+        omit<Mask extends z.util.Exactly<{ [k in keyof T]?: true; }, Mask>>(
+            mask: Mask
+        ): z.ZodObject<Omit<T, keyof Mask>, UnknownKeys, Catchall>
     }
 }
 

packages/@green-stack-core/schemas/tests/schemas.test.ts

@@ -9,6 +9,8 @@ const User = schema('User', {
     age: z.number(),
 })
 
+type User = z.infer<typeof User>
+
 test("Schemas can be introspected", () => {
     expect(User.introspect).toBeInstanceOf(Function)
     expect(User.introspect()).toEqual({
@@ -36,6 +38,8 @@ const Primitives = schema('Primitives', {
     date: z.date().default(new Date('2024-01-01')).example(new Date('2020-01-01')).describe('Date'),
 })
 
+type Primitives = z.infer<typeof Primitives>
+
 test("Optionality, defaults & example values persist in schema introspection", () => {
     const metadata = Primitives.introspect() as Meta$Schema
     // Optionality
@@ -200,6 +204,8 @@ const AdvancedTypes = schema('AdvancedTypes', {
     array: z.array(z.string()).min(0).max(5).length(1).default([]).example(['world']),
 })
 
+type AdvancedTypes = z.infer<typeof AdvancedTypes>
+
 test("Advanced types z.enum(), z.tuple(), z.union() & z.array() work as expected", () => {
     const metadata = AdvancedTypes.introspect() as Meta$Schema
     // Base Types
@@ -276,6 +282,7 @@ test("Deriving schemas with .extendSchema(), .omitSchema(), .pickSchema() work a
     const Extended = Primitives.extendSchema('Extended', {
         newField: z.string().default('Hello'),
     })
+    type Extended = z.infer<typeof Extended>
     expect(Extended.introspect().name).toBe('Extended')
     expect(Extended.introspect().schema).toHaveProperty('newField')
     expect(Extended.parse({ newField: 'World' })).toEqual({
@@ -287,6 +294,7 @@ test("Deriving schemas with .extendSchema(), .omitSchema(), .pickSchema() work a
     })
     // Omit
     const Omitted = Primitives.omitSchema('Omitted', { str: true })
+    type Omitted = z.infer<typeof Omitted>
     expect(Omitted.introspect().name).toBe('Omitted')
     expect(Omitted.introspect().schema).not.toHaveProperty('str')
     expect(Omitted.parse({ num: 42 })).toEqual({
@@ -296,6 +304,7 @@ test("Deriving schemas with .extendSchema(), .omitSchema(), .pickSchema() work a
     })
     // Pick
     const Picked = Primitives.pickSchema('Picked', { str: true })
+    type Picked = z.infer<typeof Picked>
     expect(Picked.introspect().name).toBe('Picked')
     expect(Picked.introspect().schema).toHaveProperty('str')
     expect(Picked.introspect().schema).not.toHaveProperty('num')