@kensio/yulin 1.21.24 → 1.21.26

package/docs/sdk/README.md

@@ -172,6 +172,24 @@ specific commands:
 The list accepts command classes or command names. Sending another command throws
 `SimSdkCommandNotInterceptedError`.
 
+## Abort a send
+
+An intercepted client honours the `abortSignal` option of `send`, as the SDK's own HTTP handler does:
+
+`await client.send(command, { abortSignal: AbortSignal.timeout(5000) })`
+
+A signal that has already fired rejects the send before it reaches the simulation. A signal that fires
+while the simulated operation is pending rejects the send then. A Lambda handler sleeping on the
+simulation's clock is one operation that stays pending.
+
+Either way the send rejects with an `AbortError` shaped like the one the SDK throws. Its message is
+`Request aborted` and its `cause` is the signal's reason (a `TimeoutError` for
+`AbortSignal.timeout`). Match it by `error.name`.
+
+A send carrying a signal waits one turn of the host's timers before it reaches the simulation. That
+turn stands in for the request's time on the network. A timeout of 0 or 1 milliseconds set before the
+send aborts it, as it would a request to AWS.
+
 ## Intercept the DynamoDB document client
 
 The DynamoDB document client accepts plain JavaScript values. Intercept the document client object,
@@ -282,6 +300,11 @@ 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.
+- An aborted send stops waiting for its answer. The simulated operation it started still runs to the
+  end, as a request AWS has already received does.
+- Most simulated operations answer within one turn of the host's timers. A timeout longer than a few
+  milliseconds only fires during an operation that waits, such as a sleeping Lambda handler. A
+  simulated Bedrock answer cannot be delayed.
 - 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

package/docs/services/dynamodb/README.md

@@ -1434,6 +1434,8 @@ from a different partition key is refused, since it names a collection this quer
 ## Reading a global secondary index
 
 Set `IndexName` on `Query` or `Scan` to read an index. Key conditions then use the index key schema.
+IAM authorizes the read against the index's own ARN, covered under
+[authorizing a read of an index](#authorizing-a-read-of-an-index).
 
 ```typescript sim-dynamodb-query-index
 /**
@@ -3716,6 +3718,26 @@ unauthorized caller cannot find out which names are taken.
 in the same way, each against the `dynamodb:` action of its own name. `ListTables` names no table.
 It authorizes against `*`.
 
+### Authorizing a read of an index
+
+A `Query` or `Scan` of the table authorizes against the table ARN. One naming an `IndexName`
+authorizes against the index's own ARN, the table ARN followed by `/index/` and the index name:
+
+```text
+arn:aws:dynamodb:eu-west-2:111111111111:table/OrdersTable/index/byStatus
+```
+
+Global and local secondary indexes work the same way. A statement allowing `dynamodb:Query` on the
+table ARN alone refuses a query of any index, with an `AccessDenied` naming the index ARN. A
+statement allowing only an index ARN refuses a query of the table. A caller that reads both needs
+the table ARN and `<table ARN>/index/*` (or each index ARN) in its policy.
+
+CDK's `grantReadData` and `grantReadWriteData` add `<table ARN>/index/*` only for a table construct
+that declares its indexes. A table imported with `Table.fromTableName` declares none, so its grant
+covers the table ARN alone, and a query of an index fails here as it fails on AWS. Import the table
+with `Table.fromTableAttributes` and its `globalIndexes` or `localIndexes` to have the grant cover
+them.
+
 ### Fine-grained access control with dynamodb:LeadingKeys
 
 `GetItem`, `BatchGetItem`, `Query`, `PutItem`, `UpdateItem`, `DeleteItem` and `BatchWriteItem`
@@ -3723,6 +3745,8 @@ supply the partition key values they reach as `dynamodb:LeadingKeys`. A policy c
 key restricts a caller to the items under particular partition keys. AWS scopes one user of a
 shared table to their own rows this way.
 
+A `Query` of an index supplies the index's partition key value, the value its key condition names.
+
 The condition takes the `ForAllValues:` qualifier, as AWS requires for this key. Every partition 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.
@@ -3847,6 +3871,8 @@ is written.
   answering with the attributes it projects, and paging with a `LastEvaluatedKey` carrying the index
   key and the table key together. A local secondary index also answers a strongly consistent read,
   and fetches an unprojected attribute from the base table.
+- `Query` and `Scan` of an index authorized against the index ARN, for a global and a local
+  secondary index alike.
 - `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.

package/docs/services/scheduler/README.md

@@ -303,6 +303,64 @@ regardless of `ActionAfterCompletion`.
 enabling it picks up from the next due instant. What it missed is never replayed. An update that
 changes the expression reschedules from the new one.
 
+### Flexible time windows
+
+`FlexibleTimeWindow: { Mode: "FLEXIBLE", MaximumWindowInMinutes: n }` delays each invocation by up
+to `n` minutes. The schedule still falls due at the times its expression gives. Each occurrence then
+invokes its target at a moment drawn inside `[due, due + n minutes)`. The moment is never before the
+due time and always before the window closes.
+
+The draw is made separately for every occurrence. A test that advances the clock past the end of an
+occurrence's window sees exactly one invocation for it, whatever was drawn. A test that stops inside
+the window may or may not see it. Assert after the window has closed.
+
+The draws come from the `random` source the `SimAws` was built with. It defaults to the host's
+`Math.random`, and the moments differ from run to run. Pass a `SimSeededRandom` to draw the same
+moments every time (to reproduce a failure, for example).
+
+```typescript sim-scheduler-flexible-window
+/**
+ * A schedule invoking its target up to fifteen minutes after each hour.
+ */
+
+import {
+  CreateScheduleCommand,
+  GetScheduleCommand,
+} from "@aws-sdk/client-scheduler";
+
+import { SimAws, SimSeededRandom } from "@kensio/yulin";
+
+// The same seed draws the same invocation moments on every run.
+const simAws = new SimAws({ random: new SimSeededRandom(2026) });
+
+await simAws.scheduler().createSchedule(
+  new CreateScheduleCommand({
+    Name: "hourly-digest",
+    ScheduleExpression: "cron(0 * * * ? *)",
+    FlexibleTimeWindow: { Mode: "FLEXIBLE", MaximumWindowInMinutes: 15 },
+    Target: {
+      Arn: "arn:aws:lambda:us-east-1:888888888888:function:digest",
+      RoleArn: "arn:aws:iam::888888888888:role/SchedulerRole",
+    },
+  }),
+);
+
+const described = await simAws
+  .scheduler()
+  .getSchedule(new GetScheduleCommand({ Name: "hourly-digest" }));
+
+console.log(described.FlexibleTimeWindow);
+// { Mode: "FLEXIBLE", MaximumWindowInMinutes: 15 }
+```
+
+A `FLEXIBLE` window needs `MaximumWindowInMinutes`, a whole number from 1 to 1440. An `OFF` window
+must leave it out. Either mistake is a `ValidationException`. `GetSchedule` reports the window the
+schedule was created with.
+
+A schedule deleted or replaced while an occurrence is waiting inside its window does not invoke for
+that occurrence. A one-time schedule with `ActionAfterCompletion: "DELETE"` is removed once its
+delayed invocation has been made.
+
 ## Running an ECS task on a schedule
 
 A target whose ARN names an ECS cluster runs a [simulated ECS](https://yulinsim.dev/services/ecs/)
@@ -812,6 +870,8 @@ Resources of the same stack.
   authorized against that role's own policies. Lambda targets use asynchronous Event invocation.
 - ECS targets, running a simulated task as the execution role, with the task definition and
   `TaskCount` from `EcsParameters` and container overrides from the target's `Input`.
+- `FlexibleTimeWindow` in both modes, with each `FLEXIBLE` invocation drawn inside its window from
+  the simulation's `random` source.
 - `ActionAfterCompletion`, and `deliveryFailures` for invocations that did not happen.
 - Target retry policies driven by simulated time, and standard SQS dead-letter queues carrying the
   original input and Scheduler diagnostic attributes.
@@ -829,8 +889,8 @@ Resources of the same stack.
 
 - A schedule only fires while a test advances the simulation's clock. The host's clock drives none
   of it, and a simulation left alone in real time never fires however long it is left.
-- Firing is exact and exactly once. Real Scheduler invokes within a minute of the due time, and its
-  promise is at-least-once.
+- Firing is exact and exactly once with the window `OFF`. Real Scheduler invokes within a minute of
+  the due time, and its promise is at-least-once.
 - Retry delays are deterministic powers of two seconds. Real Scheduler uses exponential backoff
   without publishing an exact sequence. The fixed sequence lets a test advance to a known retry
   instant.
@@ -844,9 +904,12 @@ Resources of the same stack.
   real Scheduler holds the group in `DELETING` until they have gone.
 - The `default` schedule group cannot be deleted. AWS leaves the answer to that request
   undocumented.
-- `FlexibleTimeWindow` with `Mode: "FLEXIBLE"` is refused. Real Scheduler invokes the target at an
-  unpredictable moment inside the window, and firing at the exact due time instead would let a test
-  rely on timing AWS leaves unpromised.
+- A flexible window draws each invocation moment uniformly, to the millisecond. AWS documents only
+  that the target is invoked inside the window after the scheduled time, and publishes no
+  distribution.
+- The wording of the refusals for a `FLEXIBLE` window with no `MaximumWindowInMinutes`, and an `OFF`
+  window with one, is Yulin's own. AWS refuses both and does not document the message. The range
+  refusals use the API's constraint wording.
 - `ScheduleExpressionTimezone` is read from the host's own timezone data through `Intl`, so a zone
   the host has never heard of is refused even where AWS would take it. A schedule that names none
   runs in UTC.

package/docs/time/README.md

@@ -247,6 +247,24 @@ Yulin uses the clock for:
 - `Date`, global timers, and invocation deadlines inside a simulated Lambda invocation
 - HTTP response `Date` headers
 
+## Values AWS leaves to chance
+
+Some AWS behaviour is unpredictable by design. An EventBridge Scheduler
+[flexible time window](https://yulinsim.dev/services/scheduler/#flexible-time-windows) invokes its
+target at a moment AWS chooses inside the window. Yulin draws those values from the `random` option
+of `SimAws`, which defaults to the host's `Math.random`.
+
+Pass a `SimSeededRandom` to draw the same values on every run:
+
+```typescript
+import { SimAws, SimSeededRandom } from "@kensio/yulin";
+
+const simAws = new SimAws({ random: new SimSeededRandom(2026) });
+```
+
+A test that advances the clock past the end of a window passes whatever was drawn. A seed is for
+reproducing a run (one that failed, for example).
+
 ## Limitations
 
 - Scheduled [EventBridge rules](https://yulinsim.dev/services/eventbridge/#rules-that-fire-on-a-schedule)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.24",
+  "version": "1.21.26",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
@@ -293,13 +293,13 @@
     "eslint-plugin-jsdoc": "^64.0.1",
     "eslint-plugin-no-secrets": "^2.3.3",
     "eslint-plugin-security": "^4.0.1",
-    "eslint-plugin-unicorn": "^73.0.0",
+    "eslint-plugin-unicorn": "^74.0.0",
     "execa": "^10.0.0",
     "fta-cli": "^3.0.0",
     "hyparquet": "^1.29.2",
     "hyparquet-writer": "^0.16.9",
     "node-sql-parser": "^5.4.0",
-    "oxfmt": "^0.70.0",
+    "oxfmt": "^0.71.0",
     "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "25.0.9",