@aglyn/aglyn 1.17.0 → 1.19.0

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.
Files changed (31) hide show
  1. package/package.json +11 -11
  2. package/src/lib/app-utils/compose-reusable-components.js +7 -3
  3. package/src/lib/app-utils/compose-reusable-components.js.map +1 -1
  4. package/src/lib/app-utils/docs-help.generated.d.ts +1 -1
  5. package/src/lib/app-utils/docs-help.generated.js +1 -0
  6. package/src/lib/app-utils/docs-help.generated.js.map +1 -1
  7. package/src/lib/app-utils/docs-index.generated.js +18 -4
  8. package/src/lib/app-utils/docs-index.generated.js.map +1 -1
  9. package/src/lib/app-utils/element-motion.js +6 -5
  10. package/src/lib/app-utils/element-motion.js.map +1 -1
  11. package/src/lib/app-utils/expand-repeatables.d.ts +23 -3
  12. package/src/lib/app-utils/expand-repeatables.js +61 -7
  13. package/src/lib/app-utils/expand-repeatables.js.map +1 -1
  14. package/src/lib/app-utils/plugin-connection-editor.d.ts +22 -0
  15. package/src/lib/app-utils/plugin-connection-editor.js.map +1 -1
  16. package/src/lib/app-utils/plugin-connection-repeat.d.ts +82 -0
  17. package/src/lib/app-utils/plugin-connection-repeat.js +162 -0
  18. package/src/lib/app-utils/plugin-connection-repeat.js.map +1 -0
  19. package/src/lib/app-utils/release-flags.js +2 -2
  20. package/src/lib/app-utils/release-flags.js.map +1 -1
  21. package/src/lib/app-utils/repeat-sources.d.ts +33 -1
  22. package/src/lib/app-utils/repeat-sources.js +27 -3
  23. package/src/lib/app-utils/repeat-sources.js.map +1 -1
  24. package/src/lib/app-utils/seo-page-facts.js +3 -6
  25. package/src/lib/app-utils/seo-page-facts.js.map +1 -1
  26. package/src/lib/plugin-manager/first-party-plugins.generated.d.ts +6 -0
  27. package/src/lib/plugin-manager/first-party-plugins.generated.js +8 -0
  28. package/src/lib/plugin-manager/first-party-plugins.generated.js.map +1 -1
  29. package/src/lib/plugin-manager/repeat-rows.d.ts +20 -2
  30. package/src/lib/plugin-manager/repeat-rows.js +42 -16
  31. package/src/lib/plugin-manager/repeat-rows.js.map +1 -1
@@ -14,7 +14,7 @@
14
14
  * See the License for the specific language governing permissions and
15
15
  * limitations under the License.
16
16
  */
17
- import type { RepeatableDataset } from '../app-utils/expand-repeatables';
17
+ import { type RepeatableDataset } from '../app-utils/expand-repeatables';
18
18
  /**
19
19
  * WHERE A PUBLISHED PAGE'S REPEATED ROWS COME FROM (AGL-3080).
20
20
  *
@@ -57,6 +57,16 @@ import type { RepeatableDataset } from '../app-utils/expand-repeatables';
57
57
  * or unreadable entry renders no copies of its element (AGL-3496) — never its
58
58
  * raw `{{item.*}}` template — and costs the page nothing else.
59
59
  *
60
+ * ## Two sources, routed by key (AGL-4212)
61
+ *
62
+ * A key `repeatKey` made from a node's `repeatConnection` starts
63
+ * `connection:`; it names a plugin connection's synced record, and goes to
64
+ * the connection source (`connectionRepeatSource` in `plugins.config.json`).
65
+ * Every other key goes to the `repeatSource`, exactly as before. Each source
66
+ * has the three cases above on its own: a page whose site has no plugin that
67
+ * keeps connection records gets no copies of a connection repeat, and still
68
+ * gets its datasets' rows.
69
+ *
60
70
  * Reached by path, never through a barrel: only the server composition asks.
61
71
  */
62
72
  /** One composition's question: the keys a page's tree repeats over. */
@@ -85,6 +95,13 @@ export interface RepeatSourceDeclaration {
85
95
  }
86
96
  /** The plugin declared to answer repeats, or `null` when none is. */
87
97
  export declare function declaredRepeatSource(): RepeatSourceDeclaration | null;
98
+ /**
99
+ * The plugin declared to answer repeats over a plugin connection's record
100
+ * (the `connection:` keys, AGL-4212), or `null` when none is.
101
+ */
102
+ export declare function declaredConnectionRepeatSource(): RepeatSourceDeclaration | null;
103
+ /** Whether a key names a plugin connection's record rather than a dataset. */
104
+ export declare const isConnectionRepeatKey: (key: string) => boolean;
88
105
  interface RegisteredReader {
89
106
  pluginId: string;
90
107
  reader: RepeatRowReader;
@@ -117,7 +134,8 @@ export declare class RepeatRowsUnavailableError extends Error {
117
134
  }
118
135
  /**
119
136
  * The rows a composition's repeats render. See the module note for what each
120
- * of the three cases answers; with no keys it answers `{}` and asks nobody.
137
+ * of the three cases answers, per source; with no keys it answers `{}` and
138
+ * asks nobody.
121
139
  */
122
140
  export declare function readRepeatRows(request: RepeatRowsRequest): Promise<RepeatRowsAnswer>;
123
141
  export {};
@@ -1,3 +1,4 @@
1
+ var _globalScope_READERS_KEY;
1
2
  /**
2
3
  * @license
3
4
  * Copyright 2026 Aglyn LLC
@@ -13,13 +14,20 @@
13
14
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
15
  * See the License for the specific language governing permissions and
15
16
  * limitations under the License.
16
- */ var _globalScope_READERS_KEY;
17
+ */ import { REPEAT_CONNECTION_KEY_PREFIX } from "../app-utils/expand-repeatables.js";
17
18
  import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
18
- import { PLUGIN_REPEAT_SOURCE_DECLARED } from "./first-party-plugins.generated.js";
19
+ import { PLUGIN_CONNECTION_REPEAT_SOURCE_DECLARED, PLUGIN_REPEAT_SOURCE_DECLARED } from "./first-party-plugins.generated.js";
19
20
  import { runPluginDeclarationsRepair } from "./plugin-declarations-repair.js";
20
21
  /** The plugin declared to answer repeats, or `null` when none is. */ export function declaredRepeatSource() {
21
22
  return PLUGIN_REPEAT_SOURCE_DECLARED;
22
23
  }
24
+ /**
25
+ * The plugin declared to answer repeats over a plugin connection's record
26
+ * (the `connection:` keys, AGL-4212), or `null` when none is.
27
+ */ export function declaredConnectionRepeatSource() {
28
+ return PLUGIN_CONNECTION_REPEAT_SOURCE_DECLARED;
29
+ }
30
+ /** Whether a key names a plugin connection's record rather than a dataset. */ export const isConnectionRepeatKey = (key)=>key.startsWith(REPEAT_CONNECTION_KEY_PREFIX);
23
31
  /**
24
32
  * One table per process, on `globalThis` (AGL-3412): the app registers from
25
33
  * `instrumentation.ts`, which Next compiles apart from the routes that read,
@@ -46,9 +54,13 @@ const readers = (_globalScope_READERS_KEY = globalScope[READERS_KEY]) != null ?
46
54
  if (!pluginId) {
47
55
  throw new Error(`repeat row reader "${id}" registered with no owner: pass { pluginId } ` + 'when registering outside a plugin register fn');
48
56
  }
49
- const declared = declaredRepeatSource();
50
- if ((declared == null ? void 0 : declared.id) === id && declared.pluginId !== pluginId) {
51
- throw new Error(`repeat source "${id}" is declared by "${declared.pluginId}"; ` + `refused a reader from "${pluginId}"`);
57
+ for (const declared of [
58
+ declaredRepeatSource(),
59
+ declaredConnectionRepeatSource()
60
+ ]){
61
+ if ((declared == null ? void 0 : declared.id) === id && declared.pluginId !== pluginId) {
62
+ throw new Error(`repeat source "${id}" is declared by "${declared.pluginId}"; ` + `refused a reader from "${pluginId}"`);
63
+ }
52
64
  }
53
65
  const held = readers.get(id);
54
66
  if (held && held.pluginId !== pluginId) {
@@ -81,28 +93,42 @@ const readers = (_globalScope_READERS_KEY = globalScope[READERS_KEY]) != null ?
81
93
  }
82
94
  /**
83
95
  * The rows a composition's repeats render. See the module note for what each
84
- * of the three cases answers; with no keys it answers `{}` and asks nobody.
96
+ * of the three cases answers, per source; with no keys it answers `{}` and
97
+ * asks nobody.
85
98
  */ export async function readRepeatRows(request) {
86
99
  const keys = [
87
100
  ...new Set(request.keys.map((key)=>key.trim()).filter(Boolean))
88
101
  ].sort();
89
102
  if (!keys.length) return {};
90
- const declared = declaredRepeatSource();
91
- if (!declared) return {};
92
- let registered = readers.get(declared.id);
93
- if (!registered) {
103
+ const connectionKeys = keys.filter(isConnectionRepeatKey);
104
+ const plainKeys = keys.filter((key)=>!isConnectionRepeatKey(key));
105
+ const asks = [
106
+ {
107
+ declared: declaredRepeatSource(),
108
+ keys: plainKeys
109
+ },
110
+ {
111
+ declared: declaredConnectionRepeatSource(),
112
+ keys: connectionKeys
113
+ }
114
+ ].filter((ask)=>ask.declared !== null && ask.keys.length > 0);
115
+ if (!asks.length) return {};
116
+ if (asks.some((ask)=>!readers.has(ask.declared.id))) {
94
117
  try {
95
118
  await runPluginDeclarationsRepair();
96
119
  } catch (error) {
97
120
  console.error('[repeat-rows] the declarations repair failed', error);
98
121
  }
99
- registered = readers.get(declared.id);
100
122
  }
101
- if (!registered) throw new RepeatRowsUnavailableError(declared);
102
- return registered.reader({
103
- hostId: request.hostId,
104
- keys
105
- });
123
+ const answers = await Promise.all(asks.map((ask)=>{
124
+ const registered = readers.get(ask.declared.id);
125
+ if (!registered) throw new RepeatRowsUnavailableError(ask.declared);
126
+ return registered.reader({
127
+ hostId: request.hostId,
128
+ keys: ask.keys
129
+ });
130
+ }));
131
+ return Object.assign({}, ...answers);
106
132
  }
107
133
 
108
134
  //# sourceMappingURL=repeat-rows.js.map
@@ -1 +1 @@
1
- {"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/repeat-rows.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { RepeatableDataset } from '../app-utils/expand-repeatables'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport { PLUGIN_REPEAT_SOURCE_DECLARED } from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * WHERE A PUBLISHED PAGE'S REPEATED ROWS COME FROM (AGL-3080).\n *\n * Any element can repeat, and the platform decides what a repeat MEANS — the\n * scope, the copies, the filter, the bound (`expand-repeatables.ts`). What it\n * does not decide is where the rows live. That is the plugin's that keeps\n * them, and the composition that renders a published page asks it here, with\n * the keys the page's tree repeats over, and never reads a collection itself.\n *\n * `repeat-sources.ts` is the editor's side of the same line: a hook the\n * besigner's canvas mounts to preview the rows. This is the server's side,\n * read once per compose, and it is a different registry because its readers\n * are different processes with different failure costs.\n *\n * ## Declared, then registered — and an absent reader is refused\n *\n * The reader is registered from the owning plugin's `serverDeclarations`\n * entry, which every app runs at boot, so every process that composes a page\n * has it before the first request. But a registry is only safe where an empty\n * one cannot be mistaken for an answer, and here it can: a page whose repeat\n * found no reader would render no copies where the author put a list, and\n * nothing anywhere would be red. That is the AGL-3025 shape on the most\n * public surface the product has.\n *\n * So the plugin that answers also DECLARES that it does, in\n * `plugins.config.json` (`repeatSource`), and the generator compiles that into\n * core. The two together tell the one case that is a real answer from the one\n * that is a broken boot:\n *\n * - nothing declared — this deployment ships no plugin that keeps rows, and a\n * repeat renders no copies, exactly as a key naming nothing does (AGL-3496);\n * - declared and registered — the reader answers;\n * - declared and NOT registered — the boot failed. The app's declarations\n * step is run again ({@link runPluginDeclarationsRepair}); if the reader is\n * still missing, {@link readRepeatRows} THROWS. A render that throws keeps\n * the page it last rendered in the cache and is loud in the logs, which is\n * the right way round for a page that would otherwise go out wrong.\n *\n * Per-key failures are the reader's to absorb, as they always were: a deleted\n * or unreadable entry renders no copies of its element (AGL-3496) — never its\n * raw `{{item.*}}` template — and costs the page nothing else.\n *\n * Reached by path, never through a barrel: only the server composition asks.\n */\n\n/** One composition's question: the keys a page's tree repeats over. */\nexport interface RepeatRowsRequest {\n /** The site being rendered. A reader answers only what that site may see. */\n hostId: string\n /**\n * The keys exactly as the nodes store them (`repeatKeys`), trimmed,\n * sorted and without repeats.\n */\n keys: readonly string[]\n}\n\n/**\n * The rows for a request, under every key the expansion looks them up by: the\n * key as the node stores it, the entry's own id, and each entry a one-hop\n * reference in the rows reads. A key with nothing to render is absent.\n */\nexport type RepeatRowsAnswer = Record<string, RepeatableDataset>\n\n/** Answers one composition's request. Never rejects for a single bad key. */\nexport type RepeatRowReader = (\n request: RepeatRowsRequest,\n) => Promise<RepeatRowsAnswer>\n\n/** The compiled declaration: which plugin answers, under which source id. */\nexport interface RepeatSourceDeclaration {\n pluginId: string\n /** The same id the plugin's editor source (`repeat-sources.ts`) uses. */\n id: string\n}\n\n/** The plugin declared to answer repeats, or `null` when none is. */\nexport function declaredRepeatSource(): RepeatSourceDeclaration | null {\n return PLUGIN_REPEAT_SOURCE_DECLARED\n}\n\ninterface RegisteredReader {\n pluginId: string\n reader: RepeatRowReader\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): the app registers from\n * `instrumentation.ts`, which Next compiles apart from the routes that read,\n * and a module-scoped map would be filled in one copy and read empty in the\n * other — the exact failure this module exists to refuse.\n */\nconst READERS_KEY = Symbol.for('@aglyn/aglyn:repeat-row-readers')\n\nconst globalScope = globalThis as typeof globalThis & {\n [READERS_KEY]?: Map<string, RegisteredReader>\n}\n\nconst readers: Map<string, RegisteredReader> =\n globalScope[READERS_KEY] ?? (globalScope[READERS_KEY] = new Map())\n\n/**\n * Registers the reader for a source. Returns the unregister, which removes it\n * only while it is still the one registered.\n *\n * The owner is the plugin whose register fn is running, or the `pluginId`\n * passed for a boot declaration, where the loader's marker is not set. A\n * registration with neither is refused, and so is one from a plugin other\n * than the one the declaration names — two readers for one source would each\n * answer for the other's rows. The same plugin registering again replaces its\n * reader (a second surface, a repeated boot).\n */\nexport function registerRepeatRowReader(\n sourceId: string,\n reader: RepeatRowReader,\n options?: { pluginId?: string },\n): () => void {\n const id = sourceId.trim()\n const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n if (!id) throw new Error('a repeat row reader needs a source id')\n if (!pluginId) {\n throw new Error(\n `repeat row reader \"${id}\" registered with no owner: pass { pluginId } ` +\n 'when registering outside a plugin register fn',\n )\n }\n const declared = declaredRepeatSource()\n if (declared?.id === id && declared.pluginId !== pluginId) {\n throw new Error(\n `repeat source \"${id}\" is declared by \"${declared.pluginId}\"; ` +\n `refused a reader from \"${pluginId}\"`,\n )\n }\n const held = readers.get(id)\n if (held && held.pluginId !== pluginId) {\n throw new Error(\n `repeat source \"${id}\" already has a reader from \"${held.pluginId}\"; ` +\n `refused \"${pluginId}\"`,\n )\n }\n const entry: RegisteredReader = { pluginId, reader }\n readers.set(id, entry)\n return () => {\n if (readers.get(id) === entry) readers.delete(id)\n }\n}\n\n/** The reader registered for a source, with its owner, or `null`. */\nexport function repeatRowReader(sourceId: string): RegisteredReader | null {\n return readers.get(sourceId) ?? null\n}\n\n/** Only for specs: forgets every registered reader. */\nexport function resetRepeatRowReadersForTests(): void {\n readers.clear()\n}\n\n/**\n * The declared source's reader was not registered, even after the app's\n * declarations step ran again. Thrown, never answered: see the module note.\n */\nexport class RepeatRowsUnavailableError extends Error {\n constructor(readonly source: RepeatSourceDeclaration) {\n super(\n `repeat source \"${source.id}\" is declared by \"${source.pluginId}\" but ` +\n 'no reader is registered in this process — its server declarations ' +\n 'did not run. Refusing to render repeats as if they had no rows.',\n )\n this.name = 'RepeatRowsUnavailableError'\n }\n}\n\n/**\n * The rows a composition's repeats render. See the module note for what each\n * of the three cases answers; with no keys it answers `{}` and asks nobody.\n */\nexport async function readRepeatRows(\n request: RepeatRowsRequest,\n): Promise<RepeatRowsAnswer> {\n const keys = [\n ...new Set(request.keys.map((key) => key.trim()).filter(Boolean)),\n ].sort()\n if (!keys.length) return {}\n const declared = declaredRepeatSource()\n if (!declared) return {}\n let registered = readers.get(declared.id)\n if (!registered) {\n try {\n await runPluginDeclarationsRepair()\n } catch (error) {\n console.error('[repeat-rows] the declarations repair failed', error)\n }\n registered = readers.get(declared.id)\n }\n if (!registered) throw new RepeatRowsUnavailableError(declared)\n return registered.reader({ hostId: request.hostId, keys })\n}\n"],"names":["globalScope","getRegisteringPluginId","PLUGIN_REPEAT_SOURCE_DECLARED","runPluginDeclarationsRepair","declaredRepeatSource","READERS_KEY","Symbol","for","globalThis","readers","Map","registerRepeatRowReader","sourceId","reader","options","id","trim","pluginId","Error","declared","held","get","entry","set","delete","repeatRowReader","resetRepeatRowReadersForTests","clear","RepeatRowsUnavailableError","source","name","readRepeatRows","request","keys","Set","map","key","filter","Boolean","sort","length","registered","error","console","hostId"],"mappings":"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"}
1
+ {"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/repeat-rows.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n REPEAT_CONNECTION_KEY_PREFIX,\n type RepeatableDataset,\n} from '../app-utils/expand-repeatables'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n PLUGIN_CONNECTION_REPEAT_SOURCE_DECLARED,\n PLUGIN_REPEAT_SOURCE_DECLARED,\n} from './first-party-plugins.generated'\nimport { runPluginDeclarationsRepair } from './plugin-declarations-repair'\n\n/**\n * WHERE A PUBLISHED PAGE'S REPEATED ROWS COME FROM (AGL-3080).\n *\n * Any element can repeat, and the platform decides what a repeat MEANS — the\n * scope, the copies, the filter, the bound (`expand-repeatables.ts`). What it\n * does not decide is where the rows live. That is the plugin's that keeps\n * them, and the composition that renders a published page asks it here, with\n * the keys the page's tree repeats over, and never reads a collection itself.\n *\n * `repeat-sources.ts` is the editor's side of the same line: a hook the\n * besigner's canvas mounts to preview the rows. This is the server's side,\n * read once per compose, and it is a different registry because its readers\n * are different processes with different failure costs.\n *\n * ## Declared, then registered — and an absent reader is refused\n *\n * The reader is registered from the owning plugin's `serverDeclarations`\n * entry, which every app runs at boot, so every process that composes a page\n * has it before the first request. But a registry is only safe where an empty\n * one cannot be mistaken for an answer, and here it can: a page whose repeat\n * found no reader would render no copies where the author put a list, and\n * nothing anywhere would be red. That is the AGL-3025 shape on the most\n * public surface the product has.\n *\n * So the plugin that answers also DECLARES that it does, in\n * `plugins.config.json` (`repeatSource`), and the generator compiles that into\n * core. The two together tell the one case that is a real answer from the one\n * that is a broken boot:\n *\n * - nothing declared — this deployment ships no plugin that keeps rows, and a\n * repeat renders no copies, exactly as a key naming nothing does (AGL-3496);\n * - declared and registered — the reader answers;\n * - declared and NOT registered — the boot failed. The app's declarations\n * step is run again ({@link runPluginDeclarationsRepair}); if the reader is\n * still missing, {@link readRepeatRows} THROWS. A render that throws keeps\n * the page it last rendered in the cache and is loud in the logs, which is\n * the right way round for a page that would otherwise go out wrong.\n *\n * Per-key failures are the reader's to absorb, as they always were: a deleted\n * or unreadable entry renders no copies of its element (AGL-3496) — never its\n * raw `{{item.*}}` template — and costs the page nothing else.\n *\n * ## Two sources, routed by key (AGL-4212)\n *\n * A key `repeatKey` made from a node's `repeatConnection` starts\n * `connection:`; it names a plugin connection's synced record, and goes to\n * the connection source (`connectionRepeatSource` in `plugins.config.json`).\n * Every other key goes to the `repeatSource`, exactly as before. Each source\n * has the three cases above on its own: a page whose site has no plugin that\n * keeps connection records gets no copies of a connection repeat, and still\n * gets its datasets' rows.\n *\n * Reached by path, never through a barrel: only the server composition asks.\n */\n\n/** One composition's question: the keys a page's tree repeats over. */\nexport interface RepeatRowsRequest {\n /** The site being rendered. A reader answers only what that site may see. */\n hostId: string\n /**\n * The keys exactly as the nodes store them (`repeatKeys`), trimmed,\n * sorted and without repeats.\n */\n keys: readonly string[]\n}\n\n/**\n * The rows for a request, under every key the expansion looks them up by: the\n * key as the node stores it, the entry's own id, and each entry a one-hop\n * reference in the rows reads. A key with nothing to render is absent.\n */\nexport type RepeatRowsAnswer = Record<string, RepeatableDataset>\n\n/** Answers one composition's request. Never rejects for a single bad key. */\nexport type RepeatRowReader = (\n request: RepeatRowsRequest,\n) => Promise<RepeatRowsAnswer>\n\n/** The compiled declaration: which plugin answers, under which source id. */\nexport interface RepeatSourceDeclaration {\n pluginId: string\n /** The same id the plugin's editor source (`repeat-sources.ts`) uses. */\n id: string\n}\n\n/** The plugin declared to answer repeats, or `null` when none is. */\nexport function declaredRepeatSource(): RepeatSourceDeclaration | null {\n return PLUGIN_REPEAT_SOURCE_DECLARED\n}\n\n/**\n * The plugin declared to answer repeats over a plugin connection's record\n * (the `connection:` keys, AGL-4212), or `null` when none is.\n */\nexport function declaredConnectionRepeatSource(): RepeatSourceDeclaration | null {\n return PLUGIN_CONNECTION_REPEAT_SOURCE_DECLARED\n}\n\n/** Whether a key names a plugin connection's record rather than a dataset. */\nexport const isConnectionRepeatKey = (key: string): boolean =>\n key.startsWith(REPEAT_CONNECTION_KEY_PREFIX)\n\ninterface RegisteredReader {\n pluginId: string\n reader: RepeatRowReader\n}\n\n/**\n * One table per process, on `globalThis` (AGL-3412): the app registers from\n * `instrumentation.ts`, which Next compiles apart from the routes that read,\n * and a module-scoped map would be filled in one copy and read empty in the\n * other — the exact failure this module exists to refuse.\n */\nconst READERS_KEY = Symbol.for('@aglyn/aglyn:repeat-row-readers')\n\nconst globalScope = globalThis as typeof globalThis & {\n [READERS_KEY]?: Map<string, RegisteredReader>\n}\n\nconst readers: Map<string, RegisteredReader> =\n globalScope[READERS_KEY] ?? (globalScope[READERS_KEY] = new Map())\n\n/**\n * Registers the reader for a source. Returns the unregister, which removes it\n * only while it is still the one registered.\n *\n * The owner is the plugin whose register fn is running, or the `pluginId`\n * passed for a boot declaration, where the loader's marker is not set. A\n * registration with neither is refused, and so is one from a plugin other\n * than the one the declaration names — two readers for one source would each\n * answer for the other's rows. The same plugin registering again replaces its\n * reader (a second surface, a repeated boot).\n */\nexport function registerRepeatRowReader(\n sourceId: string,\n reader: RepeatRowReader,\n options?: { pluginId?: string },\n): () => void {\n const id = sourceId.trim()\n const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n if (!id) throw new Error('a repeat row reader needs a source id')\n if (!pluginId) {\n throw new Error(\n `repeat row reader \"${id}\" registered with no owner: pass { pluginId } ` +\n 'when registering outside a plugin register fn',\n )\n }\n for (const declared of [\n declaredRepeatSource(),\n declaredConnectionRepeatSource(),\n ]) {\n if (declared?.id === id && declared.pluginId !== pluginId) {\n throw new Error(\n `repeat source \"${id}\" is declared by \"${declared.pluginId}\"; ` +\n `refused a reader from \"${pluginId}\"`,\n )\n }\n }\n const held = readers.get(id)\n if (held && held.pluginId !== pluginId) {\n throw new Error(\n `repeat source \"${id}\" already has a reader from \"${held.pluginId}\"; ` +\n `refused \"${pluginId}\"`,\n )\n }\n const entry: RegisteredReader = { pluginId, reader }\n readers.set(id, entry)\n return () => {\n if (readers.get(id) === entry) readers.delete(id)\n }\n}\n\n/** The reader registered for a source, with its owner, or `null`. */\nexport function repeatRowReader(sourceId: string): RegisteredReader | null {\n return readers.get(sourceId) ?? null\n}\n\n/** Only for specs: forgets every registered reader. */\nexport function resetRepeatRowReadersForTests(): void {\n readers.clear()\n}\n\n/**\n * The declared source's reader was not registered, even after the app's\n * declarations step ran again. Thrown, never answered: see the module note.\n */\nexport class RepeatRowsUnavailableError extends Error {\n constructor(readonly source: RepeatSourceDeclaration) {\n super(\n `repeat source \"${source.id}\" is declared by \"${source.pluginId}\" but ` +\n 'no reader is registered in this process — its server declarations ' +\n 'did not run. Refusing to render repeats as if they had no rows.',\n )\n this.name = 'RepeatRowsUnavailableError'\n }\n}\n\n/**\n * The rows a composition's repeats render. See the module note for what each\n * of the three cases answers, per source; with no keys it answers `{}` and\n * asks nobody.\n */\nexport async function readRepeatRows(\n request: RepeatRowsRequest,\n): Promise<RepeatRowsAnswer> {\n const keys = [\n ...new Set(request.keys.map((key) => key.trim()).filter(Boolean)),\n ].sort()\n if (!keys.length) return {}\n const connectionKeys = keys.filter(isConnectionRepeatKey)\n const plainKeys = keys.filter((key) => !isConnectionRepeatKey(key))\n const asks = [\n { declared: declaredRepeatSource(), keys: plainKeys },\n { declared: declaredConnectionRepeatSource(), keys: connectionKeys },\n ].filter(\n (ask): ask is { declared: RepeatSourceDeclaration; keys: string[] } =>\n ask.declared !== null && ask.keys.length > 0,\n )\n if (!asks.length) return {}\n if (asks.some((ask) => !readers.has(ask.declared.id))) {\n try {\n await runPluginDeclarationsRepair()\n } catch (error) {\n console.error('[repeat-rows] the declarations repair failed', error)\n }\n }\n const answers = await Promise.all(\n asks.map((ask) => {\n const registered = readers.get(ask.declared.id)\n if (!registered) throw new RepeatRowsUnavailableError(ask.declared)\n return registered.reader({ hostId: request.hostId, keys: ask.keys })\n }),\n )\n return Object.assign({}, ...answers) as RepeatRowsAnswer\n}\n"],"names":["globalScope","REPEAT_CONNECTION_KEY_PREFIX","getRegisteringPluginId","PLUGIN_CONNECTION_REPEAT_SOURCE_DECLARED","PLUGIN_REPEAT_SOURCE_DECLARED","runPluginDeclarationsRepair","declaredRepeatSource","declaredConnectionRepeatSource","isConnectionRepeatKey","key","startsWith","READERS_KEY","Symbol","for","globalThis","readers","Map","registerRepeatRowReader","sourceId","reader","options","id","trim","pluginId","Error","declared","held","get","entry","set","delete","repeatRowReader","resetRepeatRowReadersForTests","clear","RepeatRowsUnavailableError","source","name","readRepeatRows","request","keys","Set","map","filter","Boolean","sort","length","connectionKeys","plainKeys","asks","ask","some","has","error","console","answers","Promise","all","registered","hostId","Object","assign"],"mappings":"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"}