@fantastic.dev/better-stripe 0.50.0 → 0.50.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +5 -1
- package/dist/react/workflows/useWorkflowAction.d.ts.map +1 -1
- package/dist/react/workflows/useWorkflowAction.js +5 -3
- package/dist/react/workflows/useWorkflowAction.js.map +1 -1
- package/docs/metered-usage.md +123 -0
- package/docs/react-workflows.md +6 -0
- package/package.json +3 -2
- package/src/react/workflows/useWorkflowAction.commit.test.tsx +194 -0
- package/src/react/workflows/useWorkflowAction.ssr.test.tsx +20 -0
- package/src/react/workflows/useWorkflowAction.ts +13 -3
package/CHANGELOG.md
CHANGED
|
@@ -26,6 +26,20 @@
|
|
|
26
26
|
- Remove internal tracker references from public documentation and add a
|
|
27
27
|
regression check that prevents their reintroduction.
|
|
28
28
|
|
|
29
|
+
## [0.50.2](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.1...v0.50.2) (2026-10-18)
|
|
30
|
+
|
|
31
|
+
### Documentation
|
|
32
|
+
|
|
33
|
+
- start metered billing provider feasibility ([844fb74](https://github.com/FantasticDevHQ/better-stripe/commit/844fb74c30081baac16a8275a1ae73a98a5b3753))
|
|
34
|
+
|
|
35
|
+
## [0.50.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.0...v0.50.1) (2026-10-17)
|
|
36
|
+
|
|
37
|
+
### Bug Fixes
|
|
38
|
+
|
|
39
|
+
- **react:** initialize workflow refs before descendant layout effects ([b6a9da8](https://github.com/FantasticDevHQ/better-stripe/commit/b6a9da8ad0cd3043a575420bd876b1878d9ed9f4))
|
|
40
|
+
- **react:** settle commit-started workflow actions ([f1befb4](https://github.com/FantasticDevHQ/better-stripe/commit/f1befb4194dee87b0b1c54528ae4305b5b749147))
|
|
41
|
+
- **react:** settle workflow actions started during commit ([5d4d2e1](https://github.com/FantasticDevHQ/better-stripe/commit/5d4d2e1fa3623205b3f971f1e5e1c9d24919a091))
|
|
42
|
+
|
|
29
43
|
## [0.50.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.49.0...v0.50.0) (2026-10-17)
|
|
30
44
|
|
|
31
45
|
### Features
|
package/README.md
CHANGED
|
@@ -72,7 +72,7 @@ claim execution are completed.
|
|
|
72
72
|
|
|
73
73
|
## Status
|
|
74
74
|
|
|
75
|
-
**Version**: `0.50.
|
|
75
|
+
**Version**: `0.50.2` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
|
|
76
76
|
|
|
77
77
|
Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
|
|
78
78
|
|
|
@@ -1835,3 +1835,7 @@ Automatic combined payouts use a complete paginated ledger collection above 100
|
|
|
1835
1835
|
Resolve recovery-backed payout liabilities with `stripe.costRecovery.payoutQuote(ctx, authorizedScope)` and pass its amount/version together to preview or automatic release. The example does this for seller refund/dispute costs; stale or missing required versions fail safely. See [versioned liability guidance](docs/settlement.md#versioned-recovery-liabilities).
|
|
1836
1836
|
|
|
1837
1837
|
Historical payout adoption and funded-account activation also use complete paginated collections beyond the small direct snapshot path. They revalidate complete financial membership atomically, preserve paid principal and holding age, and reject stale funding or recovery changes. See [historical import guidance](docs/settlement.md#historical-import-and-funded-activation).
|
|
1838
|
+
|
|
1839
|
+
## Metered usage
|
|
1840
|
+
|
|
1841
|
+
Metered billing is under investigation. See the [provider comparison and sandbox acceptance matrix](docs/metered-usage.md) for current status and integration requirements. Public usage APIs are not available yet.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"useWorkflowAction.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"useWorkflowAction.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,IAAI;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IACtB,gFAAgF;IAChF,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AACF,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EACzD,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACrC,KAAK,GAAE,MAAkB,EACzB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAC9B,mBAAmB,CAAC,CAAC,EAAE,IAAI,CAAC,CAgE9B"}
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
"use client";
|
|
2
|
-
import { useCallback, useEffect, useRef, useState } from "react";
|
|
2
|
+
import { useCallback, useEffect, useInsertionEffect, useRef, useState, } from "react";
|
|
3
|
+
// Ref-only synchronization must precede layout effects in descendants as well.
|
|
4
|
+
const useCommitEffect = typeof window === "undefined" ? useEffect : useInsertionEffect;
|
|
3
5
|
/** Shared async action lifecycle. Scope identifies the authenticated account/resource, not authorization. */
|
|
4
6
|
export function useWorkflowAction(action, scope = "default", onSuccess) {
|
|
5
7
|
const initial = {
|
|
@@ -15,11 +17,11 @@ export function useWorkflowAction(action, scope = "default", onSuccess) {
|
|
|
15
17
|
const success = useRef(onSuccess);
|
|
16
18
|
const lifecycle = useRef({ version: 0, mounted: false });
|
|
17
19
|
const lock = useRef(null);
|
|
18
|
-
|
|
20
|
+
useCommitEffect(() => {
|
|
19
21
|
callback.current = action;
|
|
20
22
|
success.current = onSuccess;
|
|
21
23
|
}, [action, onSuccess]);
|
|
22
|
-
|
|
24
|
+
useCommitEffect(() => {
|
|
23
25
|
const version = ++lifecycle.current.version;
|
|
24
26
|
lifecycle.current.mounted = true;
|
|
25
27
|
lock.current = null;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"useWorkflowAction.js","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AACb,OAAO,
|
|
1
|
+
{"version":3,"file":"useWorkflowAction.js","sourceRoot":"","sources":["../../../src/react/workflows/useWorkflowAction.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Metered usage feasibility
|
|
2
|
+
|
|
3
|
+
Status: investigation in progress, reviewed 2026-10-18. BetterStripe does not yet
|
|
4
|
+
expose metered billing APIs. The provider, first billable unit and pricing model
|
|
5
|
+
must be selected before implementing provider-specific catalog, delivery or UI.
|
|
6
|
+
This document records the compatibility questions and repeatable access preflight.
|
|
7
|
+
It does not claim a successful billing sandbox run.
|
|
8
|
+
|
|
9
|
+
## Existing integration constraints
|
|
10
|
+
|
|
11
|
+
BetterStripe subscriptions use Accounts v2 `customer_account` identities through
|
|
12
|
+
the platform Stripe client. See `src/client/billing/subscriptions.ts` and
|
|
13
|
+
[financial ownership](financial-ownership.md). Adding a separate v1 Customer is a
|
|
14
|
+
new identity/payment-method mapping contract, not an interchangeable identifier.
|
|
15
|
+
Existing fixed-price subscriptions, checkout and settlement must keep working.
|
|
16
|
+
|
|
17
|
+
Hosts authorize actors, payers and sellers and decide which activity is billable.
|
|
18
|
+
BetterStripe will own durable acceptance, deduplication, delivery and reconciliation.
|
|
19
|
+
A provider receipt cannot authorize a tenant or prove that usage was invoiced.
|
|
20
|
+
Seller and affiliate settlement must continue to use verified paid-invoice
|
|
21
|
+
proceeds and original payment provenance.
|
|
22
|
+
|
|
23
|
+
## Provider comparison
|
|
24
|
+
|
|
25
|
+
| Concern | Stripe Billing Meters | Metronome with Stripe |
|
|
26
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
27
|
+
| Provider guidance | Stripe directs new usage integrations to Metronome, including existing flat-rate subscriptions adding usage | Recommended evaluation path for new usage integrations |
|
|
28
|
+
| Credentials | Existing Stripe key, subject to permissions and API access | Separate Metronome sandbox/account token and explicit Stripe integration enrollment |
|
|
29
|
+
| Payer identity | Guide maps meter payloads to Stripe Customer IDs; installed Stripe 23.0.0 meter types expose `by_id` only | Documented invoice delivery configuration uses `stripe_customer_id` with a `cus_` ID |
|
|
30
|
+
| Accounts v2 | `acct_` payer ingestion and invoice identity remain unverified | `customer_account` invoice delivery remains unverified; ingest aliases alone do not establish payment identity |
|
|
31
|
+
| Connect | Stripe documents connected-account requests and different rate limits; this does not prove a platform-owned Accounts v2 payer works in that realm | Multi-entity connections are documented; equivalence to Connect destination charges or separate transfers remains unverified |
|
|
32
|
+
| Catalog | Meter attached to recurring metered price | Billable metric, product, rate card and customer contract |
|
|
33
|
+
| Invoices | Stripe owns subscription invoicing | Metronome rates usage and pushes separate invoices to Stripe, including when recurring subscriptions coexist |
|
|
34
|
+
| Cost/access | Confirm account eligibility and current Billing pricing before selection | Confirm enrollment, commercial terms and extra credential acceptance before selection |
|
|
35
|
+
|
|
36
|
+
No provider is selected. Evaluate Metronome first because it is Stripe's current
|
|
37
|
+
recommendation. Adopt it only after proving the Accounts v2 and settlement
|
|
38
|
+
contracts and explicitly accepting the additional service credentials. Keep Billing
|
|
39
|
+
Meters as a comparison candidate, not an automatic fallback if access fails.
|
|
40
|
+
Neither candidate currently has proven end-to-end support in this repository.
|
|
41
|
+
|
|
42
|
+
## Pricing-model decision
|
|
43
|
+
|
|
44
|
+
The product owner must choose pay-as-you-go, included monthly units with overages,
|
|
45
|
+
or prepaid credits, and name the first billable unit. Pay-as-you-go is the proposed
|
|
46
|
+
smallest starting scope. This proposal is not approval. Other models remain
|
|
47
|
+
unselected. In particular, do not create a second wallet or infer prepaid access
|
|
48
|
+
rules from the existing balance-funding integration.
|
|
49
|
+
|
|
50
|
+
Record the unit, decimal precision, aggregation formula, billing interval, currency,
|
|
51
|
+
price/version and payer/seller scope with the decision. Host limits and entitlement
|
|
52
|
+
rules are separate from an eventually consistent provider usage total.
|
|
53
|
+
|
|
54
|
+
## Access preflight
|
|
55
|
+
|
|
56
|
+
From the repository root, inject a sandbox key as `STRIPE_SECRET_KEY` and run:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
node scripts/metering-feasibility.mjs
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Use `op run` from one persistent authorized terminal when the key is in 1Password.
|
|
63
|
+
Do not print or save the key. The script rejects non-test secret keys before making
|
|
64
|
+
any request. It makes one platform-realm GET to `/v1/billing/meters?limit=1`, pins
|
|
65
|
+
the repository's Stripe version and prints only status and verification flags.
|
|
66
|
+
It creates no meters, customers, events, subscriptions, invoices or charges.
|
|
67
|
+
|
|
68
|
+
A successful response establishes endpoint access only. A 401 or 403 is an access
|
|
69
|
+
failure, not evidence that a billing identity or model is unsupported. The script
|
|
70
|
+
has no connected-account selector and does not test that realm. It is a development
|
|
71
|
+
tool in the repository, not a public package API.
|
|
72
|
+
|
|
73
|
+
## Sandbox acceptance matrix
|
|
74
|
+
|
|
75
|
+
Run the following after credentials and product decisions are available. Capture
|
|
76
|
+
sanitized request shapes, API versions, timestamps, status codes and assertions.
|
|
77
|
+
Keep secrets and raw customer/provider payloads out of evidence and workflow state.
|
|
78
|
+
|
|
79
|
+
| Scenario | Required proof | Current result |
|
|
80
|
+
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
|
|
81
|
+
| Platform Accounts v2 payer | Meter/contract creation, ingestion, aggregate and invoice all refer to the authorized payer | Unverified |
|
|
82
|
+
| Connected seller | Prove catalog/event realm and payer ownership, destination/transfer economics and paid-invoice provenance | Unverified |
|
|
83
|
+
| Non-Connect account | Prove identity and invoice flow without silently provisioning an alternative payer | Unverified |
|
|
84
|
+
| Duplicate delivery | Same source event and provider identifier produce one aggregate contribution | Unverified |
|
|
85
|
+
| Shared meter | Two subscriptions for one customer show the actual aggregation boundary; no inferred per-subscription event targeting | Unverified |
|
|
86
|
+
| Correction | Original event, reason and receipt retained; provider cancellation window and finalized-invoice behavior demonstrated | Unverified |
|
|
87
|
+
| Invoice closeout | Original event time, delayed aggregate, finalized invoice line and payment/processing costs reconcile | Unverified |
|
|
88
|
+
| Test clocks | Determine which provider clock drives event timestamps and invoice periods, without assuming virtual time advances ingestion | Unverified |
|
|
89
|
+
| Packed consumer | Verify eventual public contracts from the built tarball with linked guides present | Deferred until public APIs exist |
|
|
90
|
+
|
|
91
|
+
For Billing Meters, event uniqueness is enforced for at least a rolling 24-hour
|
|
92
|
+
window. Acceptance permits timestamps within 35 calendar days in the past or five
|
|
93
|
+
minutes in the future. Cancellation is limited to events sent within 24 hours.
|
|
94
|
+
Aggregation is asynchronous. Accepted late events can appear in summaries without
|
|
95
|
+
changing a finalized invoice. Preserve local deduplication and an explicit unknown
|
|
96
|
+
delivery state beyond the safe retry window. Events have no subscription selector.
|
|
97
|
+
|
|
98
|
+
Metronome's quickstart uses a customer UUID or ingest alias and transaction ID,
|
|
99
|
+
string-valued numerical properties and a 34-day backdating window. Confirm exact
|
|
100
|
+
retention, correction and retry guarantees for the chosen API and account before
|
|
101
|
+
encoding them as constants. Its invoice integration documentation and Stripe's
|
|
102
|
+
integration overview use different metadata names for invoice mapping. Inspect the
|
|
103
|
+
actual sandbox invoice rather than trusting a single assumed metadata key.
|
|
104
|
+
|
|
105
|
+
## Evidence recorded so far
|
|
106
|
+
|
|
107
|
+
The repository uses Stripe 23.0.0 and pins `2026-09-30.endive`. Its installed meter
|
|
108
|
+
creation types permit `customer_mapping.type: 'by_id'`; this is a type inspection,
|
|
109
|
+
not proof that Accounts v2 ingestion is supported or unsupported. The access probe
|
|
110
|
+
has automated tests covering rejection of live/missing keys, a single read-only
|
|
111
|
+
request and sanitization of provider errors. Actual provider access, usage delivery,
|
|
112
|
+
aggregation, invoices, payment provenance and Metronome access remain unverified.
|
|
113
|
+
|
|
114
|
+
## Primary sources
|
|
115
|
+
|
|
116
|
+
- [Stripe usage-based billing](https://docs.stripe.com/billing/usage-based)
|
|
117
|
+
- [Stripe's guidance on recording usage](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage)
|
|
118
|
+
- [Record usage with the API](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api)
|
|
119
|
+
- [Create a meter event](https://docs.stripe.com/api/billing/meter-event/create)
|
|
120
|
+
- [Configure meters and corrections](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure)
|
|
121
|
+
- [How Metronome works with Stripe](https://docs.stripe.com/billing/how-metronome-works-with-stripe)
|
|
122
|
+
- [Metronome API quickstart](https://docs.metronome.com/guides/get-started/api-quickstart)
|
|
123
|
+
- [Metronome invoice integration](https://docs.metronome.com/integrations/invoice-integrations/stripe)
|
package/docs/react-workflows.md
CHANGED
|
@@ -577,6 +577,12 @@ checking that the response still belongs to the mounted scope. `useOnboarding`
|
|
|
577
577
|
uses this lifecycle for both create and continue navigation, including its
|
|
578
578
|
`window.location.assign` fallback. An old response cannot navigate after unmount
|
|
579
579
|
or scope replacement. Current requests preserve shared pending locks and errors.
|
|
580
|
+
The lifecycle and current action callbacks initialize during the browser commit
|
|
581
|
+
phase, using ref-only insertion effects before parent or child layout effects
|
|
582
|
+
can start work. These effects neither update state nor inspect DOM attachment.
|
|
583
|
+
A layout-started action
|
|
584
|
+
therefore settles normally; later unmount or scope replacement still suppresses
|
|
585
|
+
its stale result. Server rendering remains idle and invokes no action.
|
|
580
586
|
`uploadDisputeEvidence`, `EvidenceUpload` and the onboarding navigation fix shipped
|
|
581
587
|
in [0.14.0](https://github.com/FantasticDevHQ/better-stripe/releases/tag/v0.14.0).
|
|
582
588
|
Version 0.13.0 does not contain them. Consumers must upgrade to
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fantastic.dev/better-stripe",
|
|
3
|
-
"version": "0.50.
|
|
3
|
+
"version": "0.50.2",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -84,7 +84,8 @@
|
|
|
84
84
|
"docs/example-recovery-cutover.md",
|
|
85
85
|
"docs/releasing.md",
|
|
86
86
|
"docs/release-handoff.md",
|
|
87
|
-
"docs/setup-intent-recovery.md"
|
|
87
|
+
"docs/setup-intent-recovery.md",
|
|
88
|
+
"docs/metered-usage.md"
|
|
88
89
|
],
|
|
89
90
|
"scripts": {
|
|
90
91
|
"build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
// @vitest-environment jsdom
|
|
2
|
+
import { StrictMode, useLayoutEffect } from "react";
|
|
3
|
+
import {
|
|
4
|
+
act,
|
|
5
|
+
cleanup,
|
|
6
|
+
fireEvent,
|
|
7
|
+
render,
|
|
8
|
+
renderHook,
|
|
9
|
+
screen,
|
|
10
|
+
} from "@testing-library/react";
|
|
11
|
+
import { afterEach, expect, it, vi } from "vitest";
|
|
12
|
+
import { useWorkflowAction } from "./useWorkflowAction.js";
|
|
13
|
+
|
|
14
|
+
afterEach(cleanup);
|
|
15
|
+
|
|
16
|
+
function ActionConsumer({
|
|
17
|
+
startsDuringCommit,
|
|
18
|
+
}: {
|
|
19
|
+
startsDuringCommit: boolean;
|
|
20
|
+
}) {
|
|
21
|
+
const observation = useWorkflowAction(async () => "observed", "original");
|
|
22
|
+
useLayoutEffect(() => {
|
|
23
|
+
if (startsDuringCommit) void observation.run();
|
|
24
|
+
}, [startsDuringCommit, observation.run]);
|
|
25
|
+
return (
|
|
26
|
+
<div>
|
|
27
|
+
<button
|
|
28
|
+
onClick={() => {
|
|
29
|
+
void observation.run();
|
|
30
|
+
}}
|
|
31
|
+
>
|
|
32
|
+
Observe
|
|
33
|
+
</button>
|
|
34
|
+
<p>
|
|
35
|
+
{observation.isPending ? "pending" : (observation.result ?? "idle")}
|
|
36
|
+
</p>
|
|
37
|
+
</div>
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
it("completes an ordinary event-started workflow action", async () => {
|
|
42
|
+
render(<ActionConsumer startsDuringCommit={false} />);
|
|
43
|
+
fireEvent.click(screen.getByRole("button", { name: "Observe" }));
|
|
44
|
+
expect((await screen.findByText("observed")).textContent).toBe("observed");
|
|
45
|
+
expect(screen.queryByText("pending")).toBeNull();
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
it("completes an action started by a consumer layout effect", async () => {
|
|
49
|
+
render(<ActionConsumer startsDuringCommit />);
|
|
50
|
+
expect((await screen.findByText("observed")).textContent).toBe("observed");
|
|
51
|
+
expect(screen.queryByText("pending")).toBeNull();
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
it("completes the current commit-started action through StrictMode replay", async () => {
|
|
55
|
+
render(
|
|
56
|
+
<StrictMode>
|
|
57
|
+
<ActionConsumer startsDuringCommit />
|
|
58
|
+
</StrictMode>,
|
|
59
|
+
);
|
|
60
|
+
expect((await screen.findByText("observed")).textContent).toBe("observed");
|
|
61
|
+
expect(screen.queryByText("pending")).toBeNull();
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
it("uses the current callback when a layout effect starts work after rerender", async () => {
|
|
65
|
+
const first = vi.fn(async () => "first");
|
|
66
|
+
const second = vi.fn(async () => "second");
|
|
67
|
+
const { result, rerender } = renderHook(
|
|
68
|
+
({ action }) => {
|
|
69
|
+
const observation = useWorkflowAction(action);
|
|
70
|
+
useLayoutEffect(() => {
|
|
71
|
+
void observation.run();
|
|
72
|
+
}, [action, observation.run]);
|
|
73
|
+
return observation;
|
|
74
|
+
},
|
|
75
|
+
{ initialProps: { action: first } },
|
|
76
|
+
);
|
|
77
|
+
await act(async () => {});
|
|
78
|
+
expect(result.current.result).toBe("first");
|
|
79
|
+
rerender({ action: second });
|
|
80
|
+
await act(async () => {});
|
|
81
|
+
expect(result.current.result).toBe("second");
|
|
82
|
+
expect(first).toHaveBeenCalledOnce();
|
|
83
|
+
expect(second).toHaveBeenCalledOnce();
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
it("does not call success after a pending consumer unmounts", async () => {
|
|
87
|
+
let complete!: (value: string) => void;
|
|
88
|
+
const onSuccess = vi.fn();
|
|
89
|
+
const { result, unmount } = renderHook(() =>
|
|
90
|
+
useWorkflowAction(
|
|
91
|
+
() =>
|
|
92
|
+
new Promise<string>((resolve) => {
|
|
93
|
+
complete = resolve;
|
|
94
|
+
}),
|
|
95
|
+
"original",
|
|
96
|
+
onSuccess,
|
|
97
|
+
),
|
|
98
|
+
);
|
|
99
|
+
let pending!: Promise<string | undefined>;
|
|
100
|
+
act(() => {
|
|
101
|
+
pending = result.current.run();
|
|
102
|
+
});
|
|
103
|
+
unmount();
|
|
104
|
+
await act(async () => {
|
|
105
|
+
complete("discarded");
|
|
106
|
+
expect(await pending).toBeUndefined();
|
|
107
|
+
});
|
|
108
|
+
expect(onSuccess).not.toHaveBeenCalled();
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
function Child({
|
|
112
|
+
run,
|
|
113
|
+
starts,
|
|
114
|
+
}: {
|
|
115
|
+
run: () => Promise<string | undefined>;
|
|
116
|
+
starts: boolean;
|
|
117
|
+
}) {
|
|
118
|
+
useLayoutEffect(() => {
|
|
119
|
+
if (starts) void run();
|
|
120
|
+
}, [run, starts]);
|
|
121
|
+
return null;
|
|
122
|
+
}
|
|
123
|
+
function Parent({ starts, label }: { starts: boolean; label: string }) {
|
|
124
|
+
const action = useWorkflowAction(async () => label, "original");
|
|
125
|
+
return (
|
|
126
|
+
<>
|
|
127
|
+
<Child run={action.run} starts={starts} />
|
|
128
|
+
<p>{action.isPending ? "pending" : (action.result ?? "idle")}</p>
|
|
129
|
+
</>
|
|
130
|
+
);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
it("settles a parent-owned public workflow action started by its child layout effect", async () => {
|
|
134
|
+
render(<Parent starts label="observed" />);
|
|
135
|
+
expect(await screen.findByText("observed")).toBeTruthy();
|
|
136
|
+
expect(screen.queryByText("pending")).toBeNull();
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
it("uses the current parent callback when child layout starts work after an update", async () => {
|
|
140
|
+
const view = render(<Parent starts={false} label="first" />);
|
|
141
|
+
expect(screen.getByText("idle")).toBeTruthy();
|
|
142
|
+
view.rerender(<Parent starts label="second" />);
|
|
143
|
+
expect(await screen.findByText("second")).toBeTruthy();
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
it("dispatches and publishes once when a child starts its parent's action under StrictMode", async () => {
|
|
147
|
+
const action = vi.fn(async () => "current");
|
|
148
|
+
const onSuccess = vi.fn();
|
|
149
|
+
function StrictParent() {
|
|
150
|
+
const observation = useWorkflowAction(action, "original", onSuccess);
|
|
151
|
+
return (
|
|
152
|
+
<>
|
|
153
|
+
<Child run={observation.run} starts />
|
|
154
|
+
<p>
|
|
155
|
+
{observation.isPending ? "pending" : (observation.result ?? "idle")}
|
|
156
|
+
</p>
|
|
157
|
+
</>
|
|
158
|
+
);
|
|
159
|
+
}
|
|
160
|
+
render(
|
|
161
|
+
<StrictMode>
|
|
162
|
+
<StrictParent />
|
|
163
|
+
</StrictMode>,
|
|
164
|
+
);
|
|
165
|
+
expect((await screen.findByText("current")).textContent).toBe("current");
|
|
166
|
+
expect(action).toHaveBeenCalledOnce();
|
|
167
|
+
expect(onSuccess).toHaveBeenCalledExactlyOnceWith("current");
|
|
168
|
+
expect(screen.queryByText("pending")).toBeNull();
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
it("suppresses pending success and result after the scope changes", async () => {
|
|
172
|
+
let complete!: (value: string) => void;
|
|
173
|
+
const onSuccess = vi.fn();
|
|
174
|
+
const action = () =>
|
|
175
|
+
new Promise<string>((resolve) => {
|
|
176
|
+
complete = resolve;
|
|
177
|
+
});
|
|
178
|
+
const { result, rerender } = renderHook(
|
|
179
|
+
({ scope }) => useWorkflowAction(action, scope, onSuccess),
|
|
180
|
+
{ initialProps: { scope: "original" } },
|
|
181
|
+
);
|
|
182
|
+
let pending!: Promise<string | undefined>;
|
|
183
|
+
act(() => {
|
|
184
|
+
pending = result.current.run();
|
|
185
|
+
});
|
|
186
|
+
rerender({ scope: "replacement" });
|
|
187
|
+
await act(async () => {
|
|
188
|
+
complete("old");
|
|
189
|
+
expect(await pending).toBeUndefined();
|
|
190
|
+
});
|
|
191
|
+
expect(onSuccess).not.toHaveBeenCalled();
|
|
192
|
+
expect(result.current.result).toBeUndefined();
|
|
193
|
+
expect(result.current.isPending).toBe(false);
|
|
194
|
+
});
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// @vitest-environment node
|
|
2
|
+
import { renderToString } from "react-dom/server";
|
|
3
|
+
import { expect, it, vi } from "vitest";
|
|
4
|
+
import { useWorkflowAction } from "./useWorkflowAction.js";
|
|
5
|
+
|
|
6
|
+
it("renders idle on the server without invoking actions or layout effects", () => {
|
|
7
|
+
const action = vi.fn(async () => "observed");
|
|
8
|
+
const warning = vi.spyOn(console, "error").mockImplementation(() => {});
|
|
9
|
+
function Consumer() {
|
|
10
|
+
const observation = useWorkflowAction(action);
|
|
11
|
+
return <p>{observation.isPending ? "pending" : "idle"}</p>;
|
|
12
|
+
}
|
|
13
|
+
try {
|
|
14
|
+
expect(renderToString(<Consumer />)).toBe("<p>idle</p>");
|
|
15
|
+
expect(action).not.toHaveBeenCalled();
|
|
16
|
+
expect(warning).not.toHaveBeenCalled();
|
|
17
|
+
} finally {
|
|
18
|
+
warning.mockRestore();
|
|
19
|
+
}
|
|
20
|
+
});
|
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
"use client";
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
useCallback,
|
|
4
|
+
useEffect,
|
|
5
|
+
useInsertionEffect,
|
|
6
|
+
useRef,
|
|
7
|
+
useState,
|
|
8
|
+
} from "react";
|
|
9
|
+
// Ref-only synchronization must precede layout effects in descendants as well.
|
|
10
|
+
const useCommitEffect =
|
|
11
|
+
typeof window === "undefined" ? useEffect : useInsertionEffect;
|
|
12
|
+
|
|
3
13
|
export type WorkflowActionState<T, Args extends unknown[]> = {
|
|
4
14
|
isPending: boolean;
|
|
5
15
|
error: string | null;
|
|
@@ -26,11 +36,11 @@ export function useWorkflowAction<T, Args extends unknown[]>(
|
|
|
26
36
|
const success = useRef(onSuccess);
|
|
27
37
|
const lifecycle = useRef({ version: 0, mounted: false });
|
|
28
38
|
const lock = useRef<number | null>(null);
|
|
29
|
-
|
|
39
|
+
useCommitEffect(() => {
|
|
30
40
|
callback.current = action;
|
|
31
41
|
success.current = onSuccess;
|
|
32
42
|
}, [action, onSuccess]);
|
|
33
|
-
|
|
43
|
+
useCommitEffect(() => {
|
|
34
44
|
const version = ++lifecycle.current.version;
|
|
35
45
|
lifecycle.current.mounted = true;
|
|
36
46
|
lock.current = null;
|