@cocreate/api 1.31.0 → 2.0.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.
package/src/client.js CHANGED
@@ -3,12 +3,55 @@ import { getValueFromObject, dotNotationToObject } from "@cocreate/utils";
3
3
  import Observer from "@cocreate/observer";
4
4
  import Socket from "@cocreate/socket-client";
5
5
  import Actions from "@cocreate/actions";
6
- import { render } from "@cocreate/render";
7
- import "@cocreate/element-prototype";
8
-
9
- const CoCreateApi = {
6
+ import { render } from "@cocreate/render";
7
+ import "@cocreate/element-prototype";
8
+
9
+ function getEndpointGroup({ name, action, element, form }) {
10
+ const operation = String(action || "").replaceAll('"', '\\"');
11
+ const operationSelector = operation ? `[${name}="${operation}"]` : null;
12
+ const endpointSelector = `[${name}-endpoint]`;
13
+ return (
14
+ (operationSelector && element?.closest(operationSelector)) ||
15
+ element?.closest(endpointSelector) ||
16
+ (operationSelector && form?.matches?.(operationSelector) ? form : null) ||
17
+ (form?.matches?.(endpointSelector) ? form : null)
18
+ );
19
+ }
20
+
21
+ function getGroupElements({ name, action, element, form, response = false }) {
22
+ const group = getEndpointGroup({ name, action, element, form });
23
+ const stateAttribute = `${name}-${response ? "response" : "request"}`;
24
+ let elements = [];
25
+
26
+ if (group) {
27
+ elements = [group, ...group.querySelectorAll(`[${name}-key]`)].filter(
28
+ (candidate) =>
29
+ getEndpointGroup({ name, action, element: candidate, form }) === group &&
30
+ candidate.getAttribute(stateAttribute) !== "false"
31
+ );
32
+ } else if (form) {
33
+ const selector = `[${name}="${action}"]:not([${stateAttribute}="false"])`;
34
+ if (form.matches?.(selector)) elements.push(form);
35
+ elements.push(...form.querySelectorAll(selector));
36
+ }
37
+
38
+ return elements.length ? elements : element ? [element] : [];
39
+ }
40
+
41
+ const CoCreateApi = {
42
+ /**
43
+ *
44
+ * @public
45
+ * @environment client
46
+ */
10
47
  modules: {},
11
48
 
49
+ /**
50
+ * Scans declarative providers when called without a config, or registers the supplied provider config.
51
+ *
52
+ * @public
53
+ * @environment client
54
+ */
12
55
  init: function (moduleConfig) {
13
56
  if (!moduleConfig) {
14
57
  let elements = document.querySelectorAll("[api], [module]");
@@ -26,18 +69,29 @@ const CoCreateApi = {
26
69
  }
27
70
  },
28
71
 
72
+ /**
73
+ * Registers a provider, its Actions callback, DOM listeners, and observers.
74
+ *
75
+ * @public
76
+ * @environment client
77
+ */
29
78
  register: function ({ name, endPoints, options }) {
30
79
  const self = this;
31
80
  if (typeof this.modules[name] === "undefined") {
32
81
  this.modules[name] = { name, endPoints, options };
33
82
 
34
- Actions.init({
35
- name,
36
- callback: (action) => {
37
- action.form = action.form || document;
38
- self.request({ ...action, type: "action" });
39
- }
40
- });
83
+ Actions.init({
84
+ name,
85
+ callback: (action) => {
86
+ action.form = action.form || document;
87
+ return self.request({
88
+ ...action,
89
+ action: action.method,
90
+ method: undefined,
91
+ type: "action"
92
+ });
93
+ }
94
+ });
41
95
 
42
96
  const inputEvent = (element) => {
43
97
  element.addEventListener("input", (e) => {
@@ -47,7 +101,9 @@ const CoCreateApi = {
47
101
  });
48
102
  };
49
103
 
50
- let elements = document.querySelectorAll(`[${name}]`);
104
+ let elements = document.querySelectorAll(
105
+ `[${name}], [${name}-endpoint]`
106
+ );
51
107
  for (let i = 0; i < elements.length; i++) {
52
108
  inputEvent(elements[i]);
53
109
  this.request({ name, element: elements[i], type: "onload" });
@@ -56,7 +112,7 @@ const CoCreateApi = {
56
112
  Observer.init({
57
113
  name: `${name}NodeObserver`,
58
114
  types: ["addedNodes"],
59
- selector: `[${name}]`,
115
+ selector: `[${name}], [${name}-endpoint]`,
60
116
  callback: function (mutation) {
61
117
  inputEvent(mutation.target);
62
118
  self.request({
@@ -70,7 +126,7 @@ const CoCreateApi = {
70
126
  Observer.init({
71
127
  name: `${name}AttributeObserver`,
72
128
  types: ["attributes"],
73
- attributeFilter: [name],
129
+ attributeFilter: [name, `${name}-endpoint`, `${name}-method`],
74
130
  callback: function (mutation) {
75
131
  self.request({
76
132
  name,
@@ -82,10 +138,22 @@ const CoCreateApi = {
82
138
  }
83
139
  },
84
140
 
85
- request: async function (object) {
86
- if (object.element) {
87
- if (!object.method)
88
- object.method = object.element.getAttribute(object.name);
141
+ /**
142
+ * Builds and dispatches a provider request from context and associated elements.
143
+ *
144
+ * @public
145
+ * @environment client
146
+ */
147
+ request: async function (object) {
148
+ if (object.element) {
149
+ if (!object.action)
150
+ object.action = object.element.getAttribute(object.name);
151
+ const group = getEndpointGroup(object);
152
+ if (!object.endpoint)
153
+ object.endpoint =
154
+ group?.getAttribute(`${object.name}-endpoint`) || object.action;
155
+ if (!object.method)
156
+ object.method = group?.getAttribute(`${object.name}-method`);
89
157
  if (!object.key)
90
158
  object.key = object.element.getAttribute(`${object.name}-key`);
91
159
  if (!object.event)
@@ -94,38 +162,62 @@ const CoCreateApi = {
94
162
  );
95
163
  }
96
164
 
97
- if (
98
- this.modules[object.name][object.method] &&
99
- this.modules[object.name][object.method].request
100
- )
101
- this.modules[object.name][object.method].request(object);
165
+ if (
166
+ this.modules[object.name][object.action] &&
167
+ this.modules[object.name][object.action].request
168
+ )
169
+ this.modules[object.name][object.action].request(object);
102
170
  else if (
103
171
  (!object.event && object.type === "action") ||
104
172
  (object.event && object.event.includes(object.type))
105
- ) {
173
+ ) {
106
174
  object.data = await CoCreateApi.getData(object);
107
- if (Object.keys(object.data).length) CoCreateApi.send(object);
108
- }
175
+ if (
176
+ object.action ||
177
+ object.endpoint ||
178
+ object.method ||
179
+ Object.keys(object.data).length
180
+ )
181
+ return CoCreateApi.send(object);
182
+ }
109
183
  },
110
184
 
111
- response: function (object) {
112
- const name = object.name;
113
- const method = object.method;
114
- const data = object.data;
115
- if (this.modules[name][method] && this.modules[name][method].response)
116
- this.modules[name][method].response(data[name]);
117
- else if (data.error) {
185
+ /**
186
+ * Handles a response, maps values to elements, dispatches completion, and routes errors.
187
+ *
188
+ * @public
189
+ * @environment client
190
+ */
191
+ response: function (object) {
192
+ const name = object.name;
193
+ const action = object.action;
194
+ const response = object.data;
195
+ const data = response.data;
196
+ if (this.modules[name][action] && this.modules[name][action].response)
197
+ this.modules[name][action].response(data);
198
+ else if (response.error) {
199
+ object.abort?.({
200
+ code: "api-request-failed",
201
+ message: response.error?.message || String(response.error),
202
+ cause: response.error
203
+ });
118
204
  render({
119
205
  selector: `[template*='${name}']`,
120
206
  data: [
121
207
  {
122
208
  type: name,
123
- method,
209
+ action,
210
+ method: object.method,
124
211
  status: "failed",
125
- message: data.error
212
+ message: response.error
126
213
  }
127
214
  ]
128
215
  });
216
+ object.element?.dispatchEvent(
217
+ new CustomEvent("error", {
218
+ detail: { error: response.error, data: response }
219
+ })
220
+ );
129
221
  } else {
130
222
  CoCreateApi.setData(object);
131
223
 
@@ -139,36 +231,64 @@ const CoCreateApi = {
139
231
  }
140
232
  },
141
233
 
142
- send: async function (object) {
143
- object.data = await Socket.send({
144
- method: object.name + "." + object.method,
145
- [object.name]: object.data,
146
- broadcast: false,
147
- broadcastBrowser: false,
148
- status: "await"
149
- });
234
+ /**
235
+ * Sends a client request through CoCreate Socket.
236
+ *
237
+ * @public
238
+ * @environment client
239
+ */
240
+ send: async function (object) {
241
+ const isDataObject = object.data &&
242
+ typeof object.data === "object" &&
243
+ !Array.isArray(object.data);
244
+ const data = isDataObject ? { ...object.data } : object.data;
245
+ const request = {
246
+ api: object.name,
247
+ method: object.method,
248
+ endpoint: object.endpoint,
249
+ data,
250
+ broadcast: false,
251
+ broadcastClient: false
252
+ };
253
+
254
+ for (const directive of ["url", "headers", "timeout", "searchParams"]) {
255
+ const value = object[directive] ?? (isDataObject ? data[directive] : undefined);
256
+ if (value !== undefined) request[directive] = value;
257
+ if (isDataObject) delete data[directive];
258
+ }
259
+
260
+ try {
261
+ object.data = await Socket.send(request);
262
+ } catch (error) {
263
+ object.data = { error: error?.message || String(error) };
264
+ }
150
265
  this.response(object);
151
266
  },
152
267
 
153
- getData: async function ({ name, method, element, form }) {
268
+ /**
269
+ * Collects and normalizes request values from the relevant element group.
270
+ *
271
+ * @public
272
+ * @environment client
273
+ */
274
+ getData: async function ({ name, action, element, form }) {
154
275
  let data = {};
155
276
 
156
277
  if (!form && element) form = element.closest("form");
157
278
  if (!form) form = document;
158
279
 
159
- let elements;
160
- if (form)
161
- elements = form.querySelectorAll(
162
- `[${name}="${method}"]:not([${name}-request="false"])`
163
- );
164
- if (!elements || elements.length == 0) elements = [element];
280
+ const elements = getGroupElements({
281
+ name,
282
+ action,
283
+ element,
284
+ form
285
+ });
165
286
 
166
287
  for (let i = 0; i < elements.length; i++) {
167
288
  if (!elements[i] || elements[i].closest("[template]")) continue;
168
- let key = elements[i].getAttribute(`${name}-key`);
169
- if (key) {
170
- let value =
171
- elements[i].stripeElement || (await elements[i].getValue());
289
+ let key = elements[i].getAttribute(`${name}-key`);
290
+ if (key) {
291
+ let value = await elements[i].getValue();
172
292
  if (key.endsWith("[]")) {
173
293
  if (!data[key]) data[key] = [];
174
294
 
@@ -177,11 +297,6 @@ const CoCreateApi = {
177
297
  } else data[key] = value;
178
298
  }
179
299
 
180
- let endpoint = elements[i].getAttribute("endpoint");
181
- if (endpoint) {
182
- data.endpoint = endpoint;
183
- }
184
-
185
300
  if (
186
301
  elements[i].getAttribute("query") &&
187
302
  elements[i].getAttribute("query") !== "false"
@@ -207,22 +322,32 @@ const CoCreateApi = {
207
322
  return data;
208
323
  },
209
324
 
325
+ /**
326
+ * Maps response data back to matching elements using setValue or renderValue.
327
+ *
328
+ * @public
329
+ * @environment client
330
+ */
210
331
  setData: function (object) {
211
332
  const name = object.name;
212
- const data = object.data;
333
+ const data = object.data.data;
213
334
  let form = object.form;
214
335
  if (!form) form = document;
215
336
 
216
- let elements = form.querySelectorAll(
217
- `[${name}="${object.method}"]:not([${name}-response="false"])`
218
- );
219
- if (!elements || elements.length == 0) return;
337
+ const elements = getGroupElements({
338
+ name,
339
+ action: object.action,
340
+ element: object.element,
341
+ form,
342
+ response: true
343
+ });
344
+ if (!elements.length) return;
220
345
 
221
- for (let i = 0; i < elements.length; i++) {
222
- let attribute = elements[i].getAttribute(name);
223
- if (attribute) {
224
- if (elements[i].hasAttribute("actions")) continue;
225
- let templateid = elements[i].getAttribute("template_id");
346
+ for (let i = 0; i < elements.length; i++) {
347
+ if (elements[i].hasAttribute("actions")) continue;
348
+ let key = elements[i].getAttribute(`${name}-key`);
349
+ if (key) {
350
+ let templateid = elements[i].getAttribute("template_id");
226
351
  if (templateid) {
227
352
  let items = document.querySelectorAll(
228
353
  `[templateid="${templateid}"]`
@@ -233,21 +358,19 @@ const CoCreateApi = {
233
358
  data
234
359
  });
235
360
  } else if (elements[i].renderValue) {
236
- let key = elements[i].getAttribute(`${name}-key`);
237
- if (key === "{}") {
238
- elements[i].renderValue(data[name]);
361
+ if (key === "{}") {
362
+ elements[i].renderValue(data);
239
363
  } else {
240
- let value = getValueFromObject(data[name], key);
364
+ let value = getValueFromObject(data, key);
241
365
  if (typeof value === "function") {
242
366
  value = value(); // Call the function and assign its return value.
243
367
  }
244
368
  elements[i].renderValue(value);
245
369
  }
246
370
  } else {
247
- let key = elements[i].getAttribute(`${name}-key`);
248
- if (key === "{}") elements[i].setValue(data[name]);
371
+ if (key === "{}") elements[i].setValue(data);
249
372
  else {
250
- let value = getValueFromObject(data[name], key);
373
+ let value = getValueFromObject(data, key);
251
374
  if (typeof value === "function") {
252
375
  value = value(); // Call the function and assign its return value.
253
376
  }
@@ -274,3 +397,153 @@ Observer.init({
274
397
  CoCreateApi.init();
275
398
 
276
399
  export default CoCreateApi;
400
+
401
+ /**
402
+ * Declares/registers an API provider name; provider-specific attributes are derived from this name.
403
+ *
404
+ * @name api | module
405
+ * @kind member
406
+ * @attribute
407
+ * @valueType string
408
+ * @environment client
409
+ */
410
+
411
+ /**
412
+ * Provider-specific operation/action name.
413
+ *
414
+ * @name {name}
415
+ * @kind member
416
+ * @attribute
417
+ * @valueType string
418
+ * @environment client
419
+ */
420
+
421
+ /**
422
+ * Endpoint name or path; may be defined on an ancestor group.
423
+ *
424
+ * @name {name}-endpoint
425
+ * @kind member
426
+ * @attribute
427
+ * @valueType string
428
+ * @environment client
429
+ */
430
+
431
+ /**
432
+ * Provider or HTTP method.
433
+ *
434
+ * @name {name}-method
435
+ * @kind member
436
+ * @attribute
437
+ * @valueType string
438
+ * @environment client
439
+ */
440
+
441
+ /**
442
+ * Maps an element's value into request data or maps response data back to the element. A key ending in [] accumulates values into an array; {} maps the whole object.
443
+ *
444
+ * @name {name}-key
445
+ * @kind member
446
+ * @attribute
447
+ * @valueType string
448
+ * @environment client
449
+ */
450
+
451
+ /**
452
+ * Limits automatic requests to matching event types.
453
+ *
454
+ * @name {name}-event
455
+ * @kind member
456
+ * @attribute
457
+ * @valueType string
458
+ * @environment client
459
+ */
460
+
461
+ /**
462
+ * Excludes an element from request collection or response mapping when set to false.
463
+ *
464
+ * @name {name}-request | {name}-response
465
+ * @kind member
466
+ * @attribute
467
+ * @valueType boolean-like string
468
+ * @acceptedValues false
469
+ * @environment client
470
+ */
471
+
472
+ /**
473
+ * Declarative selectors recognized by this module.
474
+ *
475
+ * @name declarative-selectors
476
+ * @kind member
477
+ * @selectors
478
+ * @environment client
479
+ * @example
480
+ * ```json
481
+ * [
482
+ * "[${name}-endpoint]",
483
+ * "[${name}=\"${action}\"]:not([${stateAttribute}=\"false\"])",
484
+ * "[${name}], [${name}-endpoint]",
485
+ * "[template*='${name}']",
486
+ * "[template=\"${templateid}\"]",
487
+ * "[module], [api]"
488
+ * ]
489
+ * ```
490
+ */
491
+
492
+ /**
493
+ * Declarative actions supported or registered by this module.
494
+ *
495
+ * @name declarative-actions
496
+ * @kind member
497
+ * @actions
498
+ * @environment client
499
+ * @example
500
+ * ```json
501
+ * [
502
+ * {
503
+ * "name": "{name}",
504
+ * "description": "Actions integration registers each provider as an action; invocation requests the provider operation and processes its response."
505
+ * }
506
+ * ]
507
+ * ```
508
+ */
509
+
510
+ /**
511
+ * Declarative binding behavior for this module.
512
+ *
513
+ * @name declarative-binding
514
+ * @kind member
515
+ * @binding
516
+ * @environment client
517
+ * @example
518
+ * ```json
519
+ * {
520
+ * "selectors": [
521
+ * "[api]",
522
+ * "[module]",
523
+ * "[api-endpoint]",
524
+ * "[module-endpoint]"
525
+ * ],
526
+ * "triggers": [
527
+ * "onload",
528
+ * "input",
529
+ * "attribute change",
530
+ * "Actions invocation"
531
+ * ],
532
+ * "initializesExistingElements": true,
533
+ * "observesAddedNodes": true
534
+ * }
535
+ * ```
536
+ */
537
+
538
+ /**
539
+ * Default export contract for this module.
540
+ *
541
+ * @name api-default-export
542
+ * @kind member
543
+ * @default-export
544
+ * @environment client
545
+ * @example
546
+ * ```json
547
+ * "CoCreateApi"
548
+ * ```
549
+ */