@kensio/yulin 1.21.16 → 1.21.17

package/dist/sdk/router/sim-sdk-command-router.type.d.ts

@@ -22,6 +22,15 @@ export interface SimSdkCommandContext {
      * session needs that split, because its session ARN owns no policies.
      */
     readonly caller?: SimAwsCaller | undefined;
+    /**
+     * The SDK client the Command was sent through, when the send came from one.
+     *
+     * A route needs it only for configuration the Command itself does not
+     * carry, such as the marshalling options a `DynamoDBDocumentClient` was
+     * built with. A request bridged from the wire has no client object behind
+     * it, so this is left out there.
+     */
+    readonly client?: unknown;
 }
 /**
  * Route one intercepted SDK Command to a simulated service operation.

package/dist/sdk/sim-sdk-command-dispatcher.js

@@ -41,7 +41,7 @@ export class SimSdkCommandDispatcher {
                     .supportedCommandNames()
                     .join(", ")}`);
         }
-        return await route(command, { caller });
+        return await route(command, { caller, client });
     }
     /**
      * Get the ambient SimAws.runAs caller for this dispatcher's SimAws

package/dist/service/dynamodb/document/sim-dynamodb-document-marshall-options.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The marshalling options a document client was built with.
+ *
+ * `DynamoDBDocumentClient.from(client, { marshallOptions })` changes what the
+ * real conversion does with values it would otherwise refuse, so the simulated
+ * conversion reads the same options rather than always applying the defaults.
+ * Every one of them is off unless the client asked for it, which is how the
+ * real document client leaves them.
+ */
+export interface SimDynamoDbDocumentMarshallOptions {
+    /**
+     * Drop an undefined value out of a map, a list or a set instead of refusing
+     * it.
+     */
+    readonly removeUndefinedValues: boolean;
+    /**
+     * Write an empty string, an empty binary value and an empty set as NULL.
+     */
+    readonly convertEmptyValues: boolean;
+    /**
+     * Read a class instance as a map of its own properties.
+     */
+    readonly convertClassInstanceToMap: boolean;
+    /**
+     * Write a number outside the safe integer range, digits already lost, rather
+     * than refusing it.
+     */
+    readonly allowImpreciseNumbers: boolean;
+}
+/**
+ * What a document client built with no options of its own converts by.
+ */
+export declare const simDynamoDbDocumentMarshallDefaults: SimDynamoDbDocumentMarshallOptions;
+/**
+ * Read the marshalling options off the client a Command was sent through.
+ *
+ * `DynamoDBDocumentClient` keeps the translation config it was built with on
+ * its resolved config, which is where the real marshalling middleware reads it
+ * from. A client that named none, and anything that is not a document client
+ * at all, converts by the defaults.
+ */
+export declare function simDynamoDbDocumentMarshallOptions(client: unknown): SimDynamoDbDocumentMarshallOptions;

package/dist/service/dynamodb/document/sim-dynamodb-document-marshall-options.js

@@ -0,0 +1,36 @@
+import { isRecord } from "../../../util/type-guard/record.js";
+/**
+ * What a document client built with no options of its own converts by.
+ */
+export const simDynamoDbDocumentMarshallDefaults = {
+    removeUndefinedValues: false,
+    convertEmptyValues: false,
+    convertClassInstanceToMap: false,
+    allowImpreciseNumbers: false,
+};
+/**
+ * Read the marshalling options off the client a Command was sent through.
+ *
+ * `DynamoDBDocumentClient` keeps the translation config it was built with on
+ * its resolved config, which is where the real marshalling middleware reads it
+ * from. A client that named none, and anything that is not a document client
+ * at all, converts by the defaults.
+ */
+export function simDynamoDbDocumentMarshallOptions(client) {
+    const config = isRecord(client) ? client["config"] : undefined;
+    const translateConfig = isRecord(config)
+        ? config["translateConfig"]
+        : undefined;
+    const options = isRecord(translateConfig)
+        ? translateConfig["marshallOptions"]
+        : undefined;
+    if (!isRecord(options)) {
+        return simDynamoDbDocumentMarshallDefaults;
+    }
+    return {
+        removeUndefinedValues: options["removeUndefinedValues"] === true,
+        convertEmptyValues: options["convertEmptyValues"] === true,
+        convertClassInstanceToMap: options["convertClassInstanceToMap"] === true,
+        allowImpreciseNumbers: options["allowImpreciseNumbers"] === true,
+    };
+}

package/dist/service/dynamodb/document/sim-dynamodb-document-marshall.d.ts

@@ -1,4 +1,5 @@
 import type { SimDynamoDbAttributeValue } from "../command/item/item.types.js";
+import type { SimDynamoDbDocumentMarshallOptions } from "./sim-dynamodb-document-marshall-options.js";
 /**
  * Read a native JavaScript value as the AttributeValue it stands for.
  *
@@ -7,9 +8,9 @@ import type { SimDynamoDbAttributeValue } from "../command/item/item.types.js";
  * order, so a value that reaches a simulated table through the document client
  * is the value that would have reached the real one.
  *
- * `undefined` is refused rather than dropped. The real document client drops it
- * when the client was built with `removeUndefinedValues`, which is a translate
- * config this simulation does not read yet, so refusing is what keeps a test
- * from passing against an item AWS would have written differently.
+ * The options are the ones the document client was built with. They decide
+ * what happens to a value the defaults refuse: an undefined member, an empty
+ * string or binary value, a class instance, and a number past the range a
+ * JavaScript number holds exactly.
  */
-export declare function simDynamoDbDocumentAttributeValue(value: unknown, path: string): SimDynamoDbAttributeValue;
+export declare function simDynamoDbDocumentAttributeValue(value: unknown, path: string, options: SimDynamoDbDocumentMarshallOptions): SimDynamoDbAttributeValue;

package/dist/service/dynamodb/document/sim-dynamodb-document-marshall.js

@@ -1,6 +1,5 @@
 import { SimDynamoDbDocumentValueError } from "../error/dynamodb.error.js";
-import { isSimDynamoDbDocumentBinary } from "./sim-dynamodb-document-binary.js";
-import { isSimDynamoDbDocumentNumberValue, simDynamoDbDocumentNumberAttribute, } from "./sim-dynamodb-document-number.js";
+import { simDynamoDbDocumentScalarAttribute } from "./sim-dynamodb-document-scalar.js";
 import { simDynamoDbDocumentSetAttribute } from "./sim-dynamodb-document-set.js";
 /**
  * Read a native JavaScript value as the AttributeValue it stands for.
@@ -10,61 +9,48 @@ import { simDynamoDbDocumentSetAttribute } from "./sim-dynamodb-document-set.js"
  * order, so a value that reaches a simulated table through the document client
  * is the value that would have reached the real one.
  *
- * `undefined` is refused rather than dropped. The real document client drops it
- * when the client was built with `removeUndefinedValues`, which is a translate
- * config this simulation does not read yet, so refusing is what keeps a test
- * from passing against an item AWS would have written differently.
+ * The options are the ones the document client was built with. They decide
+ * what happens to a value the defaults refuse: an undefined member, an empty
+ * string or binary value, a class instance, and a number past the range a
+ * JavaScript number holds exactly.
  */
-export function simDynamoDbDocumentAttributeValue(value, path) {
+export function simDynamoDbDocumentAttributeValue(value, path, options) {
     if (value === undefined) {
-        throw new SimDynamoDbDocumentValueError(`${path} is undefined. The real document client drops it only when it ` +
-            `was built with removeUndefinedValues, which simulated DynamoDB does ` +
-            `not read yet, so leave the attribute out instead`);
+        throw new SimDynamoDbDocumentValueError(`${path} is undefined. Build the document client with ` +
+            `removeUndefinedValues to drop it, which is what the real one asks ` +
+            `for, or leave the attribute out instead`);
     }
     if (value === null) {
         return { NULL: true };
     }
     if (Array.isArray(value)) {
-        return { L: listMembers(value, path) };
+        return { L: listMembers(value, path, options) };
     }
-    return containerOrScalar(value, path);
+    return containerOrScalar(value, path, options);
 }
 /**
  * Read a value that is not null, undefined or a list.
  */
-function containerOrScalar(value, path) {
+function containerOrScalar(value, path, options) {
     if (value instanceof Set) {
-        return simDynamoDbDocumentSetAttribute(value, path);
+        return simDynamoDbDocumentSetAttribute(value, path, options);
     }
     if (value instanceof Map) {
-        return { M: mapEntries([...value], path) };
+        return { M: mapEntries([...value], path, options) };
     }
     if (isPlainObject(value)) {
-        return { M: mapEntries(Object.entries(value), path) };
+        return { M: mapEntries(Object.entries(value), path, options) };
     }
-    return scalar(value, path);
-}
-/**
- * Read a value that stands for one attribute on its own.
- */
-function scalar(value, path) {
-    if (isSimDynamoDbDocumentBinary(value)) {
-        return { B: value };
-    }
-    if (typeof value === "boolean") {
-        return { BOOL: value };
-    }
-    if (typeof value === "number") {
-        return simDynamoDbDocumentNumberAttribute(value, path);
+    const scalar = simDynamoDbDocumentScalarAttribute(value, path, options);
+    if (scalar !== undefined) {
+        return scalar;
     }
-    if (isSimDynamoDbDocumentNumberValue(value)) {
-        return { N: value.toAttributeValue().N };
-    }
-    if (typeof value === "bigint") {
-        return { N: value.toString() };
-    }
-    if (typeof value === "string") {
-        return { S: value };
+    // A class instance is read as a map only when the client asked for it, which
+    // is the last thing the real conversion tries before giving up. Null reached
+    // an answer of its own before any of this.
+    if (typeof value === "object" && options.convertClassInstanceToMap) {
+        const instance = value;
+        return { M: mapEntries(Object.entries(instance), path, options) };
     }
     throw new SimDynamoDbDocumentValueError(`${path} is a ${typeof value} the document client has no attribute type ` +
         `for`);
@@ -72,27 +58,35 @@ function scalar(value, path) {
 /**
  * The members of a list, with the functions left out as the real one leaves
  * them out.
+ *
+ * A dropped undefined member takes its position with it, so the members after
+ * it move up. That is what the real conversion does: it filters before it
+ * converts, rather than writing a NULL where the member was.
  */
-function listMembers(values, path) {
+function listMembers(values, path, options) {
     return values
-        .filter((member) => typeof member !== "function")
-        .map((member, index) => simDynamoDbDocumentAttributeValue(member, `${path}[${index.toString()}]`));
+        .filter((member) => typeof member !== "function" &&
+        !(member === undefined && options.removeUndefinedValues))
+        .map((member, index) => simDynamoDbDocumentAttributeValue(member, `${path}[${index.toString()}]`, options));
 }
 /**
  * The entries of a map, with the functions left out.
  */
-function mapEntries(entries, path) {
+function mapEntries(entries, path, options) {
     const attributes = {};
     for (const [name, member] of entries) {
         if (typeof member === "function") {
             continue;
         }
+        if (member === undefined && options.removeUndefinedValues) {
+            continue;
+        }
         const key = String(name);
         // Defined rather than assigned, so an attribute named `__proto__` becomes
         // an ordinary attribute instead of reaching the prototype setter. The real
         // document client assigns, and so loses that attribute.
         Object.defineProperty(attributes, key, {
-            value: simDynamoDbDocumentAttributeValue(member, `${path}.${key}`),
+            value: simDynamoDbDocumentAttributeValue(member, `${path}.${key}`, options),
             enumerable: true,
             writable: true,
             configurable: true,

package/dist/service/dynamodb/document/sim-dynamodb-document-number.d.ts

@@ -1,4 +1,5 @@
 import type { SimDynamoDbAttributeValue } from "../command/item/item.types.js";
+import type { SimDynamoDbDocumentMarshallOptions } from "./sim-dynamodb-document-marshall-options.js";
 /**
  * A value carrying its own Number attribute, which is what lib-dynamodb's
  * `NumberValue` is.
@@ -23,9 +24,10 @@ export declare function isSimDynamoDbDocumentNumberValue(value: unknown): value
  * than storing one that has already lost digits. A simulated table holds the
  * digits it is given exactly, so this refusal is the only thing standing
  * between an application and a silently rounded identifier, which is why it is
- * kept rather than relaxed. A decimal inside the range is written as it stands.
+ * kept until a client asks for `allowImpreciseNumbers` and takes the rounding
+ * on. A decimal inside the range is written as it stands.
  */
-export declare function simDynamoDbDocumentNumberAttribute(value: number, path: string): SimDynamoDbAttributeValue;
+export declare function simDynamoDbDocumentNumberAttribute(value: number, path: string, options: SimDynamoDbDocumentMarshallOptions): SimDynamoDbAttributeValue;
 /**
  * Read a Number attribute back as the document client answers with it.
  *

package/dist/service/dynamodb/document/sim-dynamodb-document-number.js

@@ -15,13 +15,15 @@ export function isSimDynamoDbDocumentNumberValue(value) {
  * than storing one that has already lost digits. A simulated table holds the
  * digits it is given exactly, so this refusal is the only thing standing
  * between an application and a silently rounded identifier, which is why it is
- * kept rather than relaxed. A decimal inside the range is written as it stands.
+ * kept until a client asks for `allowImpreciseNumbers` and takes the rounding
+ * on. A decimal inside the range is written as it stands.
  */
-export function simDynamoDbDocumentNumberAttribute(value, path) {
+export function simDynamoDbDocumentNumberAttribute(value, path, options) {
     if (!Number.isFinite(value)) {
         throw new SimDynamoDbDocumentValueError(`${path} is ${value.toString()}, and DynamoDB has no such number`);
     }
-    if (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER) {
+    if (!options.allowImpreciseNumbers &&
+        (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER)) {
         throw new SimDynamoDbDocumentValueError(`${path} is ${value.toString()}, which is outside the range a ` +
             `JavaScript number holds exactly. Write it as a bigint, or as a ` +
             `NumberValue from @aws-sdk/lib-dynamodb, so its digits survive`);

package/dist/service/dynamodb/document/sim-dynamodb-document-path.d.ts

@@ -16,10 +16,6 @@ export interface SimDynamoDbDocumentPath {
      */
     convert(value: unknown, conversion: SimDynamoDbDocumentConversion, path: string): unknown;
 }
-/**
- * A path to one attribute value.
- */
-export declare function simDynamoDbDocumentValue(): SimDynamoDbDocumentPath;
 /**
  * A path to a record or list whose every member is one attribute value, which
  * is what an Item, a Key and a set of expression values are.

package/dist/service/dynamodb/document/sim-dynamodb-document-path.js

@@ -1,10 +1,23 @@
 import { isRecord } from "../../../util/type-guard/record.js";
 /**
- * One attribute value, converted where it stands.
+ * Every attribute value of an item, a key or a set of expression values.
+ *
+ * An attribute whose value is undefined is left out rather than converted, and
+ * that happens whatever the document client was built with. The real client
+ * drops it in the same place: `removeUndefinedValues` governs the values
+ * inside an attribute, and an item is not itself one of them.
  */
-class SimDynamoDbDocumentValuePath {
+class SimDynamoDbDocumentValuesPath {
     convert(value, conversion, path) {
-        return conversion(value, path);
+        if (Array.isArray(value)) {
+            return value.map((member, index) => conversion(member, `${path}[${index.toString()}]`));
+        }
+        if (!isRecord(value)) {
+            return value;
+        }
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, member]) => member !== undefined)
+            .map(([name, member]) => [name, conversion(member, `${path}.${name}`)]));
     }
 }
 /**
@@ -55,18 +68,12 @@ class SimDynamoDbDocumentFieldsPath {
         return converted;
     }
 }
-/**
- * A path to one attribute value.
- */
-export function simDynamoDbDocumentValue() {
-    return new SimDynamoDbDocumentValuePath();
-}
 /**
  * A path to a record or list whose every member is one attribute value, which
  * is what an Item, a Key and a set of expression values are.
  */
 export function simDynamoDbDocumentValues() {
-    return simDynamoDbDocumentEach(simDynamoDbDocumentValue());
+    return new SimDynamoDbDocumentValuesPath();
 }
 /**
  * A path through every member of a record or list.

package/dist/service/dynamodb/document/sim-dynamodb-document-route.js

@@ -1,4 +1,5 @@
 import { simSdkCallerOptions, } from "../../../sdk/index.js";
+import { simDynamoDbDocumentMarshallOptions } from "./sim-dynamodb-document-marshall-options.js";
 import { simDynamoDbDocumentAttributeValue } from "./sim-dynamodb-document-marshall.js";
 import { simDynamoDbDocumentNativeValue } from "./sim-dynamodb-document-unmarshall.js";
 /**
@@ -23,7 +24,10 @@ export class SimDynamoDbDocumentRoute {
      */
     route() {
         return async (command, context) => {
-            const input = this.input.convert(command.input, (value, path) => simDynamoDbDocumentAttributeValue(value, path), "input");
+            // Read per send, as the real middleware reads it, so the same route
+            // serves document clients built with different options.
+            const options = simDynamoDbDocumentMarshallOptions(context.client);
+            const input = this.input.convert(command.input, (value, path) => simDynamoDbDocumentAttributeValue(value, path, options), "input");
             const output = await this.send(input, simSdkCallerOptions(context));
             return this.output.convert(output, (value, path) => simDynamoDbDocumentNativeValue(value, path), "output");
         };

package/dist/service/dynamodb/document/sim-dynamodb-document-scalar.d.ts

@@ -0,0 +1,13 @@
+import type { SimDynamoDbAttributeValue } from "../command/item/item.types.js";
+import type { SimDynamoDbDocumentMarshallOptions } from "./sim-dynamodb-document-marshall-options.js";
+/**
+ * Read a value that stands for one attribute on its own.
+ *
+ * The kinds are tried in the order the real conversion tries them. A value
+ * that is none of them answers with nothing, and what happens to it next is
+ * for the caller to decide.
+ *
+ * An empty string and a binary value holding no bytes are written as NULL when
+ * the client was built with `convertEmptyValues`, and as themselves otherwise.
+ */
+export declare function simDynamoDbDocumentScalarAttribute(value: unknown, path: string, options: SimDynamoDbDocumentMarshallOptions): SimDynamoDbAttributeValue | undefined;

package/dist/service/dynamodb/document/sim-dynamodb-document-scalar.js

@@ -0,0 +1,46 @@
+import { isSimDynamoDbDocumentBinary } from "./sim-dynamodb-document-binary.js";
+import { isSimDynamoDbDocumentNumberValue, simDynamoDbDocumentNumberAttribute, } from "./sim-dynamodb-document-number.js";
+/**
+ * Read a value that stands for one attribute on its own.
+ *
+ * The kinds are tried in the order the real conversion tries them. A value
+ * that is none of them answers with nothing, and what happens to it next is
+ * for the caller to decide.
+ *
+ * An empty string and a binary value holding no bytes are written as NULL when
+ * the client was built with `convertEmptyValues`, and as themselves otherwise.
+ */
+export function simDynamoDbDocumentScalarAttribute(value, path, options) {
+    if (isSimDynamoDbDocumentBinary(value)) {
+        return isEmptyLength(value) && options.convertEmptyValues
+            ? { NULL: true }
+            : { B: value };
+    }
+    if (typeof value === "boolean") {
+        return { BOOL: value };
+    }
+    if (typeof value === "number") {
+        return simDynamoDbDocumentNumberAttribute(value, path, options);
+    }
+    if (isSimDynamoDbDocumentNumberValue(value)) {
+        return { N: value.toAttributeValue().N };
+    }
+    if (typeof value === "bigint") {
+        return { N: value.toString() };
+    }
+    if (typeof value === "string") {
+        return value.length === 0 && options.convertEmptyValues
+            ? { NULL: true }
+            : { S: value };
+    }
+    return undefined;
+}
+/**
+ * Whether a value holds nothing, by the length the real conversion reads.
+ *
+ * An ArrayBuffer reports `byteLength` rather than `length`, so an empty one is
+ * not empty by this measure, and the real conversion leaves it alone too.
+ */
+function isEmptyLength(value) {
+    return value.length === 0;
+}

package/dist/service/dynamodb/document/sim-dynamodb-document-set.d.ts

@@ -1,4 +1,5 @@
 import type { SimDynamoDbAttributeValue } from "../command/item/item.types.js";
+import type { SimDynamoDbDocumentMarshallOptions } from "./sim-dynamodb-document-marshall-options.js";
 /**
  * Read a JavaScript Set as one of DynamoDB's three set attributes.
  *
@@ -8,7 +9,11 @@ import type { SimDynamoDbAttributeValue } from "../command/item/item.types.js";
  * further down, where the table reads the value. That is what the real one
  * does, so a set written this way behaves the same either side.
  *
- * DynamoDB has no empty set, so an empty one is refused rather than written as
- * something else.
+ * An undefined member is dropped when the client was built with
+ * `removeUndefinedValues`, and refused otherwise. DynamoDB has no empty set, so
+ * a set with nothing left in it is written as NULL when the client was built
+ * with `convertEmptyValues`, and refused otherwise. The two are read in that
+ * order, so a set holding nothing but undefined is an empty set by the time its
+ * size is looked at, which is where the real conversion looks at it too.
  */
-export declare function simDynamoDbDocumentSetAttribute(set: ReadonlySet<unknown>, path: string): SimDynamoDbAttributeValue;
+export declare function simDynamoDbDocumentSetAttribute(set: ReadonlySet<unknown>, path: string, options: SimDynamoDbDocumentMarshallOptions): SimDynamoDbAttributeValue;

package/dist/service/dynamodb/document/sim-dynamodb-document-set.js

@@ -10,31 +10,38 @@ import { isSimDynamoDbDocumentNumberValue, simDynamoDbDocumentNumberAttribute, }
  * further down, where the table reads the value. That is what the real one
  * does, so a set written this way behaves the same either side.
  *
- * DynamoDB has no empty set, so an empty one is refused rather than written as
- * something else.
+ * An undefined member is dropped when the client was built with
+ * `removeUndefinedValues`, and refused otherwise. DynamoDB has no empty set, so
+ * a set with nothing left in it is written as NULL when the client was built
+ * with `convertEmptyValues`, and refused otherwise. The two are read in that
+ * order, so a set holding nothing but undefined is an empty set by the time its
+ * size is looked at, which is where the real conversion looks at it too.
  */
-export function simDynamoDbDocumentSetAttribute(set, path) {
-    if (set.size === 0) {
-        throw new SimDynamoDbDocumentValueError(`${path} is an empty Set, and DynamoDB has no empty set`);
+export function simDynamoDbDocumentSetAttribute(set, path, options) {
+    const members = [...set].filter((member) => !(member === undefined && options.removeUndefinedValues));
+    if (!options.removeUndefinedValues && set.has(undefined)) {
+        throw new SimDynamoDbDocumentValueError(`${path} is a Set holding undefined. Build the document client with ` +
+            `removeUndefinedValues to drop it, which is what the real one asks for`);
     }
-    if (set.has(undefined)) {
-        throw new SimDynamoDbDocumentValueError(`${path} is a Set holding undefined. The real document client drops it ` +
-            `only when it was built with removeUndefinedValues, which simulated ` +
-            `DynamoDB does not read yet`);
+    if (members.length === 0) {
+        if (options.convertEmptyValues) {
+            return { NULL: true };
+        }
+        throw new SimDynamoDbDocumentValueError(`${path} is an empty Set, and DynamoDB has no empty set`);
     }
-    return membersAttribute([...set], path);
+    return membersAttribute(members, path, options);
 }
 /**
  * Read the members of a set that is known to hold something.
  */
-function membersAttribute(members, path) {
+function membersAttribute(members, path, options) {
     const first = members[0];
     if (typeof first === "string") {
         return { SS: members.map(String) };
     }
     if (isNumberMember(first)) {
         return {
-            NS: members.map((member, index) => numberText(member, path, index)),
+            NS: members.map((member, index) => numberText(member, path, index, options)),
         };
     }
     if (isSimDynamoDbDocumentBinary(first)) {
@@ -57,14 +64,14 @@ function isNumberMember(member) {
 /**
  * The digits one member of a number set is written with.
  */
-function numberText(member, path, index) {
+function numberText(member, path, index, options) {
     if (typeof member === "bigint") {
         return member.toString();
     }
     if (isSimDynamoDbDocumentNumberValue(member)) {
         return member.toAttributeValue().N;
     }
-    const attribute = simDynamoDbDocumentNumberAttribute(Number(member), `${path}[${index.toString()}]`);
+    const attribute = simDynamoDbDocumentNumberAttribute(Number(member), `${path}[${index.toString()}]`, options);
     // A number attribute is the only thing that function answers with.
     return attribute.N ?? "";
 }

package/docs/sdk/README.md

@@ -282,7 +282,8 @@ service throws `SimSdkUnknownServiceError`.
 - Simulated errors have SDK-shaped `name` and `$metadata` fields. They are separate classes from the
   SDK exceptions, so match them by `error.name` instead of `instanceof`.
 - The callback form of `send(command, callback)` is not supported. Use the promise form.
-- Yulin ignores the translation options in
-  `DynamoDBDocumentClient.from(client, { marshallOptions, unmarshallOptions })`. The conversion uses
-  the defaults. `removeUndefinedValues: true` has no effect. Yulin refuses an `undefined` attribute
-  that the configured document client would otherwise remove.
+- Yulin reads the `marshallOptions` in
+  `DynamoDBDocumentClient.from(client, { marshallOptions, unmarshallOptions })` and ignores the
+  `unmarshallOptions`. A stored value comes back the way a document client built with no options of
+  its own reads it. See
+  [the DynamoDB docs](https://yulinsim.dev/services/dynamodb/#marshalling-options).

package/docs/services/dynamodb/README.md

@@ -3040,6 +3040,84 @@ Intercept the document client itself. `DynamoDBDocumentClient.from(client)` buil
 outside the `DynamoDBClient` class, so intercepting the base client leaves Commands sent through the
 document one untouched. See [the SDK docs](https://yulinsim.dev/sdk/#the-dynamodb-document-client).
 
+### Marshalling options
+
+`DynamoDBDocumentClient.from(client, { marshallOptions })` changes what the conversion does with a
+value the defaults refuse. Yulin reads those options off the client each Command was sent through.
+Two document clients over one simulation each convert by their own.
+
+- `removeUndefinedValues` drops an `undefined` out of a map, a list or a `Set`. Without it, an
+  `undefined` in any of the three is refused. The real client refuses it in the same place.
+- `convertEmptyValues` writes an empty string, an empty binary value and an empty `Set` as `NULL`.
+- `convertClassInstanceToMap` reads an object with behaviour as a map of its own properties.
+- `allowImpreciseNumbers` writes a number past `Number.MAX_SAFE_INTEGER` with the digits it has
+  already been rounded to.
+
+An `undefined` attribute of an item, a key or a set of expression values is left out whatever the
+client was built with. `removeUndefinedValues` governs the values held inside an attribute, and the
+attributes of an item sit a level above that (the real client drops an undefined one there without
+being asked to).
+
+```typescript sim-dynamodb-document-marshall-options
+/**
+ * Writing a partly filled object through a document client that drops
+ * undefined values.
+ */
+
+import { CreateTableCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+} from "@aws-sdk/lib-dynamodb";
+
+import { SimSdk } from "@kensio/yulin/sdk";
+
+using simSdk = new SimSdk();
+
+const documents = DynamoDBDocumentClient.from(
+  new DynamoDBClient({ region: "eu-west-2" }),
+  { marshallOptions: { removeUndefinedValues: true } },
+);
+simSdk.intercept(documents);
+
+await documents.send(
+  new CreateTableCommand({
+    TableName: "PagesTable",
+    KeySchema: [{ AttributeName: "pageId", KeyType: "HASH" }],
+    AttributeDefinitions: [{ AttributeName: "pageId", AttributeType: "S" }],
+    BillingMode: "PAY_PER_REQUEST",
+  }),
+);
+await simSdk.simAws.backgroundTasksComplete();
+
+// The summary was never filled in, and one section is still to be written.
+await documents.send(
+  new PutCommand({
+    TableName: "PagesTable",
+    Item: {
+      pageId: "page-1",
+      meta: { title: "Home", summary: undefined },
+      sections: ["intro", undefined, "outro"],
+    },
+  }),
+);
+
+const read = await documents.send(
+  new GetCommand({ TableName: "PagesTable", Key: { pageId: "page-1" } }),
+);
+
+const meta = read.Item?.["meta"] as Record<string, string>;
+console.log(Object.keys(meta)); // [ 'title' ]
+
+// A dropped member takes its position with it.
+const sections = read.Item?.["sections"] as string[];
+console.log(sections); // [ 'intro', 'outro' ]
+```
+
+`unmarshallOptions` are ignored. A stored value comes back the way a document client built with no
+options of its own reads it.
+
 ### Querying and scanning through the document client
 
 `@aws-sdk/lib-dynamodb` names its `QueryCommand` and `ScanCommand` exactly as
@@ -3152,8 +3230,9 @@ A simulated table holds a number's digits exactly, but the document client conve
 JavaScript numbers, and that is where digits are lost. It is the same loss AWS has. A test that
 passes here is telling you something true about the real thing.
 
-- Writing a `number` outside the safe integer range is refused, never stored already rounded. Write
-  a `bigint`, or a `NumberValue` from `@aws-sdk/lib-dynamodb`, to keep the digits.
+- Writing a `number` outside the safe integer range is refused unless the client was built with
+  `allowImpreciseNumbers`. Write a `bigint`, or a `NumberValue` from `@aws-sdk/lib-dynamodb`, to keep
+  the digits.
 - Reading a stored number outside the safe integer range gives a `bigint`.
 - Reading a stored decimal with more digits than a JavaScript number carries gives a rounded
   `number`. The table still holds every digit, and the rounding is the document client's. Read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.16",
+  "version": "1.21.17",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",