@platformatic/sql-mapper 3.71.1-alpha.0 → 4.0.0-alpha.1

package/index.d.ts

@@ -220,44 +220,88 @@ interface Count {
 }
 
 interface Insert<EntityFields> {
+  (options: {
+    /**
+     * Entity to insert.
+     */
+    input: EntityFields,
+    /**
+     * List of fields to be returned for the object.
+     */
+    fields?: string[],
+    /**
+     * If present, the entity participates in transaction.
+     */
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allows authorization rules
+     * and other hooks to be applied to database queries.
+     */
+    ctx?: PlatformaticContext
+  }): Promise<Partial<EntityFields>>
+}
+
+interface InsertMany<EntityFields> {
   (options: {
     /**
      * Entities to insert.
      */
     inputs: EntityFields[],
     /**
-     * List of fields to be returned for each object
+     * List of fields to be returned for each object.
      */
     fields?: string[],
     /**
-     * If present, the entity participates in transaction
+     * If present, the entities participate in transaction.
      */
     tx?: Database,
     /**
-     * Passing this to all sql-mapper functions allow to apply
-     * authorization rules to the database queries (amongst other things).
+     * Passing this to all sql-mapper functions allows authorization rules
+     * and other hooks to be applied to database queries.
      */
     ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>[]>
 }
 
-interface Save<EntityFields> {
+interface Update<EntityFields> {
   (options: {
     /**
-     * Entity to save.
+     * Entity fields to update. All primary keys must be present.
+     */
+    input: Partial<EntityFields>,
+    /**
+     * List of fields to be returned for the object.
+     */
+    fields?: string[],
+    /**
+     * If present, the entity participates in transaction.
+     */
+    tx?: Database,
+    /**
+     * Passing this to all sql-mapper functions allows authorization rules
+     * and other hooks to be applied to database queries.
+     */
+    ctx?: PlatformaticContext
+  }): Promise<Partial<EntityFields> | null>
+}
+
+interface Upsert<EntityFields> {
+  (options: {
+    /**
+     * Entity to insert or update.
      */
     input: EntityFields,
     /**
-     * List of fields to be returned for each object
+     * List of fields to be returned for the object.
      */
     fields?: string[],
     /**
-     * If present, the entity participates in transaction
+     * If present, the entity participates in transaction.
      */
     tx?: Database,
     /**
-     * Passing this to all sql-mapper functions allow to apply
-     * authorization rules to the database queries (amongst other things).
+     * Passing this to all sql-mapper functions allows authorization rules
+     * and other hooks to be applied to database queries.
      */
     ctx?: PlatformaticContext
   }): Promise<Partial<EntityFields>>
@@ -361,13 +405,30 @@ export interface Entity<EntityFields = any> {
    */
   find: Find<EntityFields>,
   /**
-   * Inserts entities to the database.
+   * Inserts an entity into the database.
    */
   insert: Insert<EntityFields>,
   /**
-   * Saves entity to the database.
+   * Inserts multiple entities into the database.
+   */
+  insertMany: InsertMany<EntityFields>,
+  /**
+   * Updates an entity by its primary keys.
+   */
+  update: Update<EntityFields>,
+  /**
+   * Updates one or more entity rows in the database.
    */
-  save: Save<EntityFields>,
+  updateMany: UpdateMany<EntityFields>,
+  /**
+   * Inserts or updates an entity.
+   */
+  upsert: Upsert<EntityFields>,
+  /**
+   * Inserts or updates an entity.
+   * @deprecated Use `upsert` instead.
+   */
+  save: Upsert<EntityFields>,
   /**
    * Deletes entities from the database.
    */
@@ -376,10 +437,6 @@ export interface Entity<EntityFields = any> {
    * Count the entities considering the where condition.
    */
   count: Count,
-  /**
-   * Update one or more entity rows from the database.
-   */
-  updateMany: UpdateMany<EntityFields>
 }
 
 type EntityHook<T extends (...args: any) => any> = (original: T, ...options: Parameters<T>) => ReturnType<T>
@@ -387,10 +444,14 @@ type EntityHook<T extends (...args: any) => any> = (original: T, ...options: Par
 export interface EntityHooks<EntityFields = any> {
   find?: EntityHook<Find<EntityFields>>,
   insert?: EntityHook<Insert<EntityFields>>,
-  save?: EntityHook<Save<EntityFields>>,
+  insertMany?: EntityHook<InsertMany<EntityFields>>,
+  update?: EntityHook<Update<EntityFields>>,
+  updateMany?: EntityHook<UpdateMany<EntityFields>>,
+  upsert?: EntityHook<Upsert<EntityFields>>,
+  /** @deprecated Use the `upsert` hook instead. */
+  save?: EntityHook<Upsert<EntityFields>>,
   delete?: EntityHook<Delete<EntityFields>>,
-  count?: EntityHook<Count>,
-  updateMany?: EntityHook<UpdateMany<EntityFields>>
+  count?: EntityHook<Count>
 }
 
 interface BasePoolOptions {

package/lib/entity.js

@@ -5,6 +5,7 @@ import { buildCursorCondition } from './cursor.js'
 import {
   InputNotProvidedError,
   InvalidPrimaryKeyTypeError,
+  MissingValueForPrimaryKeyError,
   MissingWhereClauseError,
   ParamNotAllowedError,
   UnknownFieldError,
@@ -146,50 +147,30 @@ function createMapper (
     return newOutput
   }
 
-  async function save (args) {
-    const db = getDB(args)
+  async function insert (args) {
     if (args.input === undefined) {
       throw new InputNotProvidedError()
     }
-    // args.input is not array
+
+    const db = getDB(args)
     const fieldsToRetrieve = computeFields(args.fields).map(f => sql.ident(f))
     const input = fixInput(args.input)
 
-    let hasPrimaryKeys = true
-    for (const key of primaryKeys) {
-      if (input[key] === undefined) {
-        hasPrimaryKeys = false
-        break
+    if (autoTimestamp) {
+      const now = new Date()
+      if (fields[autoTimestamp.createdAt]) {
+        input[autoTimestamp.createdAt] = now
       }
-    }
-
-    let now
-    if (autoTimestamp && fields[autoTimestamp.updatedAt]) {
-      now = new Date()
-      input[autoTimestamp.updatedAt] = now
-    }
-    if (hasPrimaryKeys) {
-      // update
-      const res = await queries.updateOne(db, sql, table, schema, input, primaryKeys, fieldsToRetrieve)
-      if (res) {
-        return fixOutput(res)
+      if (fields[autoTimestamp.updatedAt]) {
+        input[autoTimestamp.updatedAt] = now
       }
-      // If we are here, the record does not exist, so we create it
-      // this is inefficient because it will do 2 queries.
-      // TODO there is a way to do it in one query with DB specific syntax.
     }
 
-    // insert
-    if (autoTimestamp && fields[autoTimestamp.createdAt]) {
-      /* istanbul ignore next */
-      now = now || new Date()
-      input[autoTimestamp.createdAt] = now
-    }
     const res = await queries.insertOne(db, sql, table, schema, input, primaryKeysTypes, fieldsToRetrieve)
     return fixOutput(res)
   }
 
-  async function insert (args) {
+  async function insertMany (args) {
     const db = getDB(args)
     const fieldsToRetrieve = computeFields(args.fields).map(f => sql.ident(f))
     const inputs = args.inputs
@@ -240,6 +221,53 @@ function createMapper (
     }
   }
 
+  async function update (args) {
+    if (args.input === undefined) {
+      throw new InputNotProvidedError()
+    }
+
+    const db = getDB(args)
+    const fieldsToRetrieve = computeFields(args.fields).map(f => sql.ident(f))
+    const input = fixInput(args.input)
+
+    for (const key of primaryKeys) {
+      if (input[key] === undefined) {
+        throw new MissingValueForPrimaryKeyError(key)
+      }
+    }
+
+    if (autoTimestamp && fields[autoTimestamp.updatedAt]) {
+      input[autoTimestamp.updatedAt] = new Date()
+    }
+
+    const res = await queries.updateOne(db, sql, table, schema, input, primaryKeys, fieldsToRetrieve)
+    return res ? fixOutput(res) : null
+  }
+
+  async function upsert (args) {
+    if (args.input === undefined) {
+      throw new InputNotProvidedError()
+    }
+
+    const input = fixInput(args.input)
+    let hasPrimaryKeys = true
+    for (const key of primaryKeys) {
+      if (input[key] === undefined) {
+        hasPrimaryKeys = false
+        break
+      }
+    }
+
+    if (hasPrimaryKeys) {
+      const updated = await entity.update(args)
+      if (updated) {
+        return updated
+      }
+    }
+
+    return entity.insert(args)
+  }
+
   async function updateMany (args) {
     if (args.input === undefined) {
       throw new InputNotProvidedError()
@@ -508,9 +536,12 @@ function createMapper (
 
   if (!isView) {
     entity.insert = insert
-    entity.save = save
-    entity.delete = _delete
+    entity.insertMany = insertMany
+    entity.update = update
     entity.updateMany = updateMany
+    entity.upsert = upsert
+    entity.save = upsert
+    entity.delete = _delete
   }
 
   return entity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/sql-mapper",
-  "version": "3.71.1-alpha.0",
+  "version": "4.0.0-alpha.1",
   "description": "A data mapper utility for SQL databases",
   "main": "index.js",
   "type": "module",
@@ -35,11 +35,11 @@
     "camelcase": "^6.3.0",
     "fastify-plugin": "^6.0.0",
     "inflected": "^2.1.0",
-    "@platformatic/foundation": "3.71.1-alpha.0",
-    "@platformatic/telemetry": "3.71.1-alpha.0"
+    "@platformatic/foundation": "4.0.0-alpha.1",
+    "@platformatic/tracing": "4.0.0-alpha.1"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.20.0"
   },
   "scripts": {
     "lint": "eslint",