@kensio/yulin 1.21.13 → 1.21.15

package/dist/util/background/background.js

@@ -79,12 +79,14 @@ export class BackgroundTasks {
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
      *
-     * Work waiting on the clock is not waited for: it is not outstanding, it is
-     * scheduled for a simulated instant that has not arrived. Only moving the
-     * clock releases it.
+     * What happens to work waiting on the clock follows the clock. Where
+     * simulated time stands still the work stays where it is, scheduled for an
+     * instant only a caller can bring, and this returns without it. Where
+     * simulated time runs, the instant arrives by itself and this waits for the
+     * work to get through it.
      */
     async complete() {
-        await this.pending.complete();
+        await this.pending.complete(this.clockIsRunning);
     }
     /**
      * See how many outstanding background tasks are scheduled.
@@ -98,4 +100,12 @@ export class BackgroundTasks {
     get dueTaskCount() {
         return this.dueTasks.size;
     }
+    /**
+     * Whether simulated time reaches a scheduled instant on its own.
+     *
+     * A clock with nothing to say about it advances, as the host clock does.
+     */
+    get clockIsRunning() {
+        return this.clock.advances !== false;
+    }
 }

package/dist/util/background/non-deterministic-background.d.ts

@@ -55,6 +55,10 @@ export declare class NonDeterministicBackgroundTasks implements BackgroundSchedu
     /**
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
+     *
+     * Work waiting on the clock is waited for where simulated time runs, and
+     * left where it is where simulated time stands still, exactly as it is on
+     * the deterministic scheduler.
      */
     complete(): Promise<void>;
     /**

package/dist/util/background/non-deterministic-background.js

@@ -79,9 +79,13 @@ export class NonDeterministicBackgroundTasks {
     /**
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
+     *
+     * Work waiting on the clock is waited for where simulated time runs, and
+     * left where it is where simulated time stands still, exactly as it is on
+     * the deterministic scheduler.
      */
     async complete() {
-        await this.pending.complete();
+        await this.pending.complete(this.clock.advances !== false);
     }
     /**
      * See how many outstanding background tasks are scheduled.

package/dist/util/clock/sim-clock.d.ts

@@ -11,6 +11,18 @@ export interface SimClock {
      * Get the current time in this simulation.
      */
     now(): Date;
+    /**
+     * Whether simulated time moves on this clock by itself.
+     *
+     * A scheduler reads this to decide what waiting for a simulation to settle
+     * means. Time that advances brings the instant a task is scheduled for on
+     * its own, and settling waits for that task. Time that stands still leaves
+     * the instant to whoever moves the clock, and settling leaves the task where
+     * it is.
+     *
+     * A clock that says nothing advances, as the host clock does.
+     */
+    readonly advances?: boolean;
 }
 /**
  * Clock that reports the real system time.
@@ -19,6 +31,8 @@ export interface SimClock {
  * something deliberately replaces it.
  */
 export declare class SimRealClock implements SimClock {
+    /** Real time moves by itself. */
+    readonly advances = true;
     /**
      * Get the current real system time.
      */
@@ -31,6 +45,8 @@ export declare class SimRealClock implements SimClock {
  * reaching for a library that replaces the clock for the whole process.
  */
 export declare class SimFixedClock implements SimClock {
+    /** A fixed instant is the whole of this clock. Time stands still on it. */
+    readonly advances = false;
     private readonly instant;
     constructor(instant: Date);
     /**

package/dist/util/clock/sim-clock.js

@@ -5,6 +5,8 @@
  * something deliberately replaces it.
  */
 export class SimRealClock {
+    /** Real time moves by itself. */
+    advances = true;
     /**
      * Get the current real system time.
      */
@@ -19,6 +21,8 @@ export class SimRealClock {
  * reaching for a library that replaces the clock for the whole process.
  */
 export class SimFixedClock {
+    /** A fixed instant is the whole of this clock. Time stands still on it. */
+    advances = false;
     instant;
     constructor(instant) {
         this.instant = new Date(instant);

package/dist/util/clock/sim-controllable-clock.d.ts

@@ -33,6 +33,17 @@ export declare class SimControllableClock implements SimClock {
      * Whether simulated time is currently standing still.
      */
     get isFrozen(): boolean;
+    /**
+     * Whether simulated time moves here by itself.
+     *
+     * A frozen clock moves only where something moves it. So does a running
+     * clock over a base that stands still. The offset a running mode applies is
+     * fixed, so simulated time here moves exactly as far as the clock underneath
+     * moves, and a fixed clock underneath moves nowhere. Freezing and resuming
+     * such a clock changes which instant it reports and leaves it as still as it
+     * was.
+     */
+    get advances(): boolean;
     /**
      * Stop simulated time where it currently reads.
      */

package/dist/util/clock/sim-controllable-clock.js

@@ -32,6 +32,19 @@ export class SimControllableClock {
     get isFrozen() {
         return this.mode.isFrozen;
     }
+    /**
+     * Whether simulated time moves here by itself.
+     *
+     * A frozen clock moves only where something moves it. So does a running
+     * clock over a base that stands still. The offset a running mode applies is
+     * fixed, so simulated time here moves exactly as far as the clock underneath
+     * moves, and a fixed clock underneath moves nowhere. Freezing and resuming
+     * such a clock changes which instant it reports and leaves it as still as it
+     * was.
+     */
+    get advances() {
+        return !this.mode.isFrozen && this.base.advances !== false;
+    }
     /**
      * Stop simulated time where it currently reads.
      */

package/docs/services/dynamodb/README.md

@@ -3648,6 +3648,22 @@ The condition takes the `ForAllValues:` qualifier, as AWS requires for this key.
 value the request reaches has to match. A batch or a write naming one item outside the allowed set
 is refused whole, and nothing it asked for is applied.
 
+The same commands, along with `Scan`, supply the top-level attribute names they reach as
+`dynamodb:Attributes`. A name reaches the condition wherever the request writes one, in a
+`ProjectionExpression`, an `UpdateExpression`, a `ConditionExpression`, a `FilterExpression`, a
+`KeyConditionExpression`, and in the `Key` or `Item` a request names outright. A `#` placeholder is
+resolved first, so the policy is matched against the attribute rather than the alias. A nested path
+counts as the attribute it starts at, so `address.city` reaches `address`.
+
+A policy conditioned on `dynamodb:Attributes` has to name every primary key and index key attribute
+of the table alongside the attributes it is restricting, as AWS requires. A request names its key,
+and a policy leaving the key attributes out refuses every request that reads or writes an item.
+
+A request reaching no attribute at all leaves the key out of the condition context, which a
+`ForAllValues:` condition matches. A `Scan` carrying no expression is the case to watch. AWS asks
+for a `Null` check beside such a statement to close it, covered under
+[policy conditions](https://yulinsim.dev/services/iam/#policy-conditions).
+
 ```typescript sim-dynamodb-leading-keys
 import { CreateTableCommand, PutItemCommand } from "@aws-sdk/client-dynamodb";
 import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
@@ -3755,6 +3771,8 @@ is written.
 - `dynamodb:LeadingKeys` on `GetItem`, `BatchGetItem`, `Query`, `PutItem`, `UpdateItem`,
   `DeleteItem` and `BatchWriteItem`, carrying the partition key values the request reaches so a
   `ForAllValues:` condition can scope a caller to particular items.
+- `dynamodb:Attributes` on those seven and on `Scan`, carrying the top-level attribute names the
+  request reaches, read from every expression it carries and from its `Key` or `Item`.
 - `DescribeTable`, answering with the full table description, by table name or ARN.
 - `ListTables`, ordered by UTF-8 bytes and paged with `Limit` and `ExclusiveStartTableName`.
 - `DeleteTable`, following the table status DynamoDB moves a deleted table through, and refusing a
@@ -3828,10 +3846,11 @@ Arn`, `Fn::GetAtt … StreamArn` and `Fn::GetAtt … TableId` answering. A CDK `
 
 ## Limitations
 
-- `dynamodb:LeadingKeys` is the only DynamoDB condition key supplied. `dynamodb:Attributes`,
-  `dynamodb:Select` and `dynamodb:ReturnValues` are absent from the condition context, and a
-  statement conditioned on one of them matches no request. The transactional operations supply no
-  leading keys either, and are authorized by action and table alone.
+- `dynamodb:LeadingKeys` and `dynamodb:Attributes` are the DynamoDB condition keys supplied.
+  `dynamodb:Select`, `dynamodb:ReturnValues`, `dynamodb:ReturnConsumedCapacity` and the numbered
+  partition key families are absent from the condition context, and a statement conditioned on one
+  of them matches no request. The transactional operations supply neither key, and are authorized by
+  action and table alone.
 - A partition key value reaches a policy condition as a string for a `S` key and as its digits for
   an `N` key. A binary partition key has no documented form for the condition key. A request
   carrying one leaves the value out.

package/docs/services/iam/README.md

@@ -236,7 +236,7 @@ repository that still says it is there.
 ## Policy conditions
 
 Policy statements can carry `Condition` blocks. Sim IAM currently supports the `StringEquals`,
-`StringLike`, `ArnLike`, `ArnEquals` and `NumericLessThanEquals` operators, along with the
+`StringLike`, `ArnLike`, `ArnEquals`, `NumericLessThanEquals` and `Null` operators, along with the
 `ForAllValues:` and `ForAnyValue:` set variants of `StringEquals` and `StringLike`.
 
 The negated operators `StringNotEquals`, `StringNotLike`, `ArnNotEquals` and `ArnNotLike` are
@@ -337,8 +337,20 @@ request value is there to satisfy it.
 
 A `ForAllValues:` operator answers true for an absent key, which is also AWS behaviour. Every value
 the request carries matches when it carries none. AWS warns that this leaves a `ForAllValues:`
-`Allow` overly permissive, and asks for a `Null` check with a `false` value beside it. `Null` is
-absent from the operators above. A statement written that way fails closed here.
+`Allow` overly permissive, and asks for a `Null` check with a `false` value beside it. Write the
+guard and sim IAM evaluates it.
+
+`Null` asks whether the request carries a value for a context key rather than comparing one. `"true"`
+matches where the key is absent and `"false"` where it is present. A key carrying an empty string or
+an empty list of values counts as absent, which is the null dataset AWS describes. The two values
+can also be written as JSON booleans. Any other policy value leaves the condition matching nothing.
+
+```json
+"Condition": {
+  "ForAllValues:StringLike": { "dynamodb:LeadingKeys": ["ORDER#*"] },
+  "Null": { "dynamodb:LeadingKeys": "false" }
+}
+```
 
 ### Statements left unevaluated
 
@@ -1689,6 +1701,8 @@ Sim IAM models the policy behaviour that multi-service tests most commonly need.
 - Only the condition operators listed above are supported. A statement using any other operator
   fails closed, matching no request. `decision.unevaluatedStatements` names those statements, and a
   test can assert that a decision was reached over policies read in full
+- The `...IfExists` operator suffix is absent. AWS reads it as the sibling of `Null`, treating a
+  condition on a key the request leaves out as true. A statement using it fails closed here
 - A positive `ForAllValues:` condition fails to match an empty value set, where AWS matches one. An
   absent context key matches, as it does on AWS. A service here leaves a key out where the request
   carries no value for it, and the empty set is reached only by a caller passing one to `authorize`

package/docs/services/lambda/README.md

@@ -3269,6 +3269,17 @@ An interval runs once for each period an advance covers. Advancing eleven second
 interval runs it five times. A delay of zero, or none at all, is due at the instant it was asked
 for, and a handler yielding with `setTimeout(resolve, 0)` gets going again without the clock moving.
 
+Where the clock is left running, the delay passes in real time and nothing has to move it.
+`simAws.backgroundTasksComplete()` waits for a handler sleeping on a clock that is moving. An S3
+event notification, a stream record or an asynchronous invocation whose handler uses a timer has
+finished by the time the drain returns, and the function's `Timeout` bounds how long that wait can
+last.
+
+Two things leave a clock standing still. `freeze()`, `advanceBy(...)` and `setTo(...)` all leave it
+frozen, and a `SimAws` built on a `SimFixedClock` reports one instant however long the host runs.
+Under either the drain comes back while the handler sleeps, and moving the clock is what releases
+it.
+
 The function's `Timeout` is a deadline on the same clock. Where it arrives before the handler
 answers, the invocation ends in the error the real runtime reports.
 

package/docs/time/README.md

@@ -63,6 +63,13 @@ example, a simulation advanced by one hour continues to run one hour ahead of th
 
 Read `simAws.clock().isFrozen` to check the current mode.
 
+The mode also decides what waiting for the simulation to settle means.
+`simAws.backgroundTasksComplete()` waits for background work sleeping on a clock that is moving,
+because the instant that work sleeps until arrives by itself. Under a clock standing still the same
+work is left where it is, and `advanceBy(...)` or a forward `setTo(...)` is what brings the instant
+and waits for what follows from it. A simulation built on a `SimFixedClock` stands still under a
+running mode too, since simulated time here moves only as far as the clock underneath moves.
+
 ## Advancing time
 
 `advanceBy(...)` accepts days, hours, minutes, seconds, and milliseconds. The values are added

package/package.json

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