@foxtware/mineral 0.1.39 → 0.1.40
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/AGENTS.md +5 -0
- package/api/UTILS.md +52 -0
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Notes for AI assistants working in this directory. **Read this file at the start of mineral tasks** and follow anything here that isn't overridden by the user in chat.
|
|
4
4
|
|
|
5
|
+
## Related docs
|
|
6
|
+
|
|
7
|
+
- Utils landmarks (`Processor`, `canFinish`, `Getter`, …): [`api/UTILS.md`](api/UTILS.md)
|
|
8
|
+
- Function layout templates: `api/_example.js`, `api/[platform]/_example*.js`
|
|
9
|
+
|
|
5
10
|
## Misc
|
|
6
11
|
- When working in shopify, refer to gids (gid://shopify/Page/12345678) explicitly as "gids", and use "id" to refer to the number itself (12345678). "id" may still be required for use of the GraphQL API but semantically we should make this distinction.
|
|
7
12
|
- funcApiConfig should not list `options` in `argNames` — it is optional. When present on the request body, `funcApi` appends it after the named args.
|
package/api/UTILS.md
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Mineral utils landmarks
|
|
2
|
+
|
|
3
|
+
Cheat sheet for [`utils.js`](utils.js). Prefer this over cold-grepping the file. Exports are listed near the bottom of `utils.js` (`module.exports`).
|
|
4
|
+
|
|
5
|
+
## Validation and args
|
|
6
|
+
|
|
7
|
+
| Export | Use when |
|
|
8
|
+
|--------|----------|
|
|
9
|
+
| `ArgsWarden` | Validate required function args. Do **not** list `options` in `argNames` — `funcApi` appends body `options` after named args. |
|
|
10
|
+
| `credsFromPayload` | Resolve `{ credsPath }` / `{ credsObject }` / `{ credsProvider }` into creds. |
|
|
11
|
+
| `valueProvided` | Default ArgsWarden singleton validator (“anything truthy/present”). |
|
|
12
|
+
| `objHasAny` / `objHasAll` | Object-shape validators (e.g. product identifier has `productId` or `handle`). |
|
|
13
|
+
|
|
14
|
+
## Queues and batching
|
|
15
|
+
|
|
16
|
+
| Export | Use when |
|
|
17
|
+
|--------|----------|
|
|
18
|
+
| `Processor` | Drain a mutable pile with concurrency. Constructor options include `canFinish` (default `true`), `maxInFlightRequests`, `logFlavourText`, `onDone`. Set `this.canFinish = false` (or pass `canFinish: false`) to keep waiting when the pile is empty until you flip it true — useful when producers still fill the pile. |
|
|
19
|
+
| `oneTrickProcessor` | Fire-and-forget: pile of arg arrays → `func(...args)` via a `Processor`. |
|
|
20
|
+
| `actionSingleOrMultiple` | Single resource action that also accepts an array (or cartesian product of arrays) via `OperationQueue`. |
|
|
21
|
+
| `Operation` / `OperationQueue` | Lower-level queue primitives behind `actionSingleOrMultiple`. |
|
|
22
|
+
| `Getter` | Paginated list fetch: `paginator` + `digester`; export both `platformThingGet` and `platformThingGetter` with `.bind`-style wrappers. Call `getter.end()` to stop paging early. `run({ verbose })` defaults to quiet when `HOSTED`. |
|
|
23
|
+
| `FakeGetter` | Wrap a one-shot fetch (e.g. Peoplevox report) so it emits `items` / `done` like a `Getter`. |
|
|
24
|
+
| `ThresholdActioner` | Call an action once N `increment()` calls have happened (e.g. unlock a tagger after processors finish). |
|
|
25
|
+
| `MultiDex` | Index items by multiple primary keys and merge partial records (useful for cross-store joins). |
|
|
26
|
+
|
|
27
|
+
## Shopify ids
|
|
28
|
+
|
|
29
|
+
| Export | Use when |
|
|
30
|
+
|--------|----------|
|
|
31
|
+
| `gidToId` | Strip `gid://shopify/.../123` → `"123"`. Prefer numeric **id** inputs on mineral functions; use **gid** only when the GraphQL API requires it. |
|
|
32
|
+
|
|
33
|
+
## HTTP client
|
|
34
|
+
|
|
35
|
+
| Export | Use when |
|
|
36
|
+
|--------|----------|
|
|
37
|
+
| `FetchClient` | Platform HTTP client base (pipeline steps, base URL, auth). |
|
|
38
|
+
| `customFetch` | Shared fetch used inside clients; already sets `Content-Type: application/json` when there is a body — don’t set it again. |
|
|
39
|
+
| `fetchClient` option | Many handlers accept `fetchClient` in `options` so geode (or tests) can inject a wrapped client. |
|
|
40
|
+
|
|
41
|
+
## Diff / inspect (sweeps)
|
|
42
|
+
|
|
43
|
+
| Export | Use when |
|
|
44
|
+
|--------|----------|
|
|
45
|
+
| `surveyObject` | Summarise / compare object fields for assess steps. |
|
|
46
|
+
| `diffObjects` | Field-level diffs between source and target. |
|
|
47
|
+
| `logDeep` | Deep console dump (local inspect). |
|
|
48
|
+
| `askQuestion` | Interactive confirm when `!HOSTED`. |
|
|
49
|
+
|
|
50
|
+
## Small helpers often needed
|
|
51
|
+
|
|
52
|
+
`ensureArray`, `arrayToChunks`, `groupObjectsByFields`, `arrayPartition`, `wait`, `timeMs`, `responseArrayToResponse`, `responseResultsByOutcome`, `normalise`, `objectDigNodeAtPath`.
|