Merge changes from v3.0.0-next.2 into main (#218)

Author: trevor-anderson

.vscode/settings.json

@@ -17,12 +17,22 @@
   // vscode-icons
   "vsicons.associations.files": [
     // https://github.com/vscode-icons/vscode-icons/blob/master/src/iconsManifest/supportedExtensions.ts
+    {
+      "icon": "tsconfig",
+      "extensions": [],
+      "filenamesGlob": ["tsconfig", "tsconfig.build-cjs", "tsconfig.build-esm"],
+      "extensionsGlob": ["json"],
+      "filename": true,
+      "format": "svg"
+    },
     {
       "icon": "vitest",
-      /* The below configs get the vitest icon applied to the setup-file, but this does
-        not conform to documented usage, and frankly I don't know why it works. */
-      "extensions": ["vitest.setup.ts"],
-      "filename": ["vitest.setup.ts"]
+      "filenamesGlob": ["vitest.config", "vitest.setup"],
+      "extensions": [],
+      "extensionsGlob": ["ts"],
+      "filename": true,
+      "languages": ["vitestsnapshot"],
+      "format": "svg"
     }
   ]
 }

CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+# [3.0.0-next.2](https://github.com/Nerdware-LLC/ddb-single-table/compare/v3.0.0-next.1...v3.0.0-next.2) (2025-07-01)
+
+# [3.0.0-next.1](https://github.com/Nerdware-LLC/ddb-single-table/compare/v2.13.0...v3.0.0-next.1) (2025-07-01)
+
+
+### Bug Fixes
+
+* add `ReadonlyArray` type for ITFS compat ([84f70df](https://github.com/Nerdware-LLC/ddb-single-table/commit/84f70dfff8e3e671442b1820addc2437356070f7))
+* add checks for `Date` objects in `recurse` fn, update types ([7b24cd4](https://github.com/Nerdware-LLC/ddb-single-table/commit/7b24cd43c5488c51ebc5240520b87390ec9bec6b))
+* replace `NativeAttributeValue` w `SupportedAttributeValueType` for Dates ([4a0dd06](https://github.com/Nerdware-LLC/ddb-single-table/commit/4a0dd06243f40a9be85eb97e719736e4e7ca9b8d))
+* replace inline `string | number` w `AttrValue` generic for correct typing ([e9adeaa](https://github.com/Nerdware-LLC/ddb-single-table/commit/e9adeaa06c12490f3373dbd6edb7fe9028632f3d))
+* update named import for 'EnsureTableIsActiveParameters' ([bae628a](https://github.com/Nerdware-LLC/ddb-single-table/commit/bae628a09ea0512341126e29755a462399bca44c))
+
+
+### Code Refactoring
+
+* mv Date-conversion from Model IO-Action to `DdbClientFieldParser` ([d2a574c](https://github.com/Nerdware-LLC/ddb-single-table/commit/d2a574cc76ba576b159927e6f8dfd8dfe100a7a6))
+* update Model methods to use new `DdbClientWrapper` return values ([e8a7bb5](https://github.com/Nerdware-LLC/ddb-single-table/commit/e8a7bb5064699be6571d5ea948f96d4914a17dd3))
+
+
+### Features
+
+* add `getRecursiveValueConverter` ([38cc316](https://github.com/Nerdware-LLC/ddb-single-table/commit/38cc316487f82f7720fc2bcf41853c065c13cb5a))
+* add `isValidDatetimeString` ([33c97b3](https://github.com/Nerdware-LLC/ddb-single-table/commit/33c97b3abfddcaf301b333f51397fd9b6f67d2c0))
+* add `UnknownItem` type, update `BaseItem` to use `SupportedAttributeValueType` ([ffec182](https://github.com/Nerdware-LLC/ddb-single-table/commit/ffec1826576aefb5bb0faa1941d0ac9b5a678209))
+* add DdbClientArgParser for improved command argument handling and response parsing ([bdba380](https://github.com/Nerdware-LLC/ddb-single-table/commit/bdba380165321163295d6ae6d37b6e7f9a658dab))
+* add export of `Model/types/*` ([8e6b95f](https://github.com/Nerdware-LLC/ddb-single-table/commit/8e6b95f63067a4e121f73baff982c70567174637))
+* add FixPartialUndefined and OverrideSharedProperties types ([6a10d78](https://github.com/Nerdware-LLC/ddb-single-table/commit/6a10d78684cc9c189b0253a6b23dad2343b37042))
+* add type `AttributeFunctionDefault` ([77dd84e](https://github.com/Nerdware-LLC/ddb-single-table/commit/77dd84ea2a7dde3ad6fddd81e5f4eae34bfe1931))
+* rm export of NestDepth internal util types ([4fd364e](https://github.com/Nerdware-LLC/ddb-single-table/commit/4fd364e13d46f4d30784c6e4ad5dcc4994ece442))
+
+
+### Reverts
+
+* switch `transformItem` and `validateItem` param types back to `any` ([00b2525](https://github.com/Nerdware-LLC/ddb-single-table/commit/00b25253150b24132e57f4b515b39f46e298ad21))
+
+
+### BREAKING CHANGES
+
+* `schemaWithKeysOnly` has been rm'd, and batch methods filter unproc'd reqs.
+* Date-conversion has been moved from `Model` to `DdbClientFieldParser`.
+
 # [2.13.0](https://github.com/Nerdware-LLC/ddb-single-table/compare/v2.12.1...v2.13.0) (2025-06-15)
 
 

README.md

@@ -303,7 +303,10 @@ Marshalling ✅ Validation ✅ Where-style query API ✅ and more. <br>
 
 ## 🧙‍♂️ Data IO Order of Operations
 
-When any Model method is invoked, it begins a request-response cycle in which DDB-ST applies a series of transformations and validations to ensure that the data conforms to the schema defined for the Model. DDB-ST collectively refers to these transformations and validations as _"**IO-Actions**"_, and they are categorized into two groups: `toDB` and `fromDB`. The `toDB` actions are applied to Model-method arguments before they're passed off to the underlying AWS SDK, while the `fromDB` actions are applied to all values returned from the AWS SDK before they're returned to the caller.
+When any Model method is invoked, it begins a request-response cycle in which DDB-ST applies a series of transformations and validations to ensure that the data conforms to the schema defined for the Model. DDB-ST collectively refers to these transformations and validations as _"**IO-Actions**"_, and they are categorized into two groups — `toDB` and `fromDB`:
+
+- `toDB` actions are applied to Model-method arguments before they're passed off to the underlying AWS SDK.
+- `fromDB` actions are applied to all values returned from the AWS SDK before they're returned to the caller.
 
 The `toDB` and `fromDB` flows both have a specific order in which **IO-Actions** are applied.
 
@@ -321,17 +324,15 @@ The `toDB` and `fromDB` flows both have a specific order in which **IO-Actions**
 |   5   | [**`Type Checking`**](#type)                      | Checks properties for conformance with their `"type"`. |                      |
 |   6   | [**`Attribute Validation`**](#validate)           | Validates individual item properties.                  |                      |
 |   7   | [**`Item Validation`**](#validateitem)            | Validates an item in its entirety.                     | `updateItem`         |
-|   8   | [**`Convert JS Types`**](#type)                   | Converts JS types into DynamoDB types.                 |                      |
-|   9   | [**`"Required" Checks`**](#required)              | Checks for `"required"` and `"nullable"` attributes.   | `updateItem`         |
+|   8   | [**`"Required" Checks`**](#required)              | Checks for `"required"` and `"nullable"` attributes.   | `updateItem`         |
 
 ### `fromDB`
 
 | Order | IO-Action                                           | Description                                        |
 | :---: | :-------------------------------------------------- | :------------------------------------------------- |
-|   1   | [**`Convert JS Types`**](#type)                     | Converts DynamoDB types into JS types.             |
-|   2   | [**`Attribute fromDB Modifiers`**](#transformvalue) | Runs your `transformValue.fromDB` functions.       |
-|   3   | [**`Item fromDB Modifier`**](#transformitem)        | Runs your `transformItem.fromDB` function.         |
-|   4   | [**`Alias Mapping`**](#alias)                       | Replaces attribute names with attribute _aliases_. |
+|   1   | [**`Attribute fromDB Modifiers`**](#transformvalue) | Runs your `transformValue.fromDB` functions.       |
+|   2   | [**`Item fromDB Modifier`**](#transformitem)        | Runs your `transformItem.fromDB` function.         |
+|   3   | [**`Alias Mapping`**](#alias)                       | Replaces attribute names with attribute _aliases_. |
 
 ## 📖 Schema API
 
@@ -580,12 +581,10 @@ Optional default value to apply. This can be configured as either a straight-for
 > With the exception of `updateItem` calls, an attribute's value is set to this `default` if the initial value provided to the Model method is `undefined` or `null`.
 
 - ##### When using a primitive-value `default`
-
   - The primitive's type must match the attribute's `type`, otherwise the Model's
     constructor will throw an error.
 
 - ##### When using a function `default`
-
   - The function is called with the entire item-object provided to the Model method _**with
     UNALIASED keys**_, and the attribute value is set to the function's returned value.
   - _This package does not validate functional `default`s._
@@ -808,7 +807,6 @@ DDB-ST models provide a high-level API for batching CRUD operations that handles
 1. First request: no delay
 2. Second request: delay `initialDelay` milliseconds (_default:_ 100)
 3. All subsequent request delays are equal to the previous delay multiplied by the `timeMultiplier` (_default:_ 2), until either:
-
    - The `maxRetries` limit is reached (_default:_ 10), or
    - The `maxDelay` limit is reached (_default:_ 3500, or 3.5 seconds)
 
@@ -833,6 +831,7 @@ DDB-ST models provide a high-level API for batching CRUD operations that handles
 **A:** DDB-ST provides a wrapper around the DynamoDB client:
 
 - To simplify client usage, the wrapper handles all marshalling and unmarshalling of data to/from DynamoDB types.
+- The wrapper also handles conversion of JS `Date` objects to/from ISO-8601 datetime strings.
 - To ensure client resources like socket connections are cleaned up, a listener is attached to the process "exit" event which calls the client's `destroy()` method.
 
 ### Q: _What version of the AWS SDK does DDB-ST use?_<!-- omit in toc -->

eslint.config.js

@@ -1,3 +1,5 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import eslintJS from "@eslint/js";
 import stylisticPlugin from "@stylistic/eslint-plugin";
 import vitestPlugin from "@vitest/eslint-plugin";
@@ -22,7 +24,9 @@ export default tsEslint.config(
       parser: tsEslint.parser,
       parserOptions: {
         projectService: true,
-        tsconfigRootDir: import.meta.dirname,
+        tsconfigRootDir: dirname(fileURLToPath(import.meta.url)),
+        /* Note: use `tsconfigRootDir: import.meta.dirname` once "engines.node"
+          gets bumped to ">=22.0.0" (NodeJS v20 will reach EOL on April 30, 2026). */
       },
     },
     plugins: {