@medyll/idae-machine 0.129.0 → 0.135.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.
Files changed (101) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +360 -393
  3. package/cli.js +46 -0
  4. package/dist/demo/dbSchema.d.ts +446 -0
  5. package/dist/demo/dbSchema.js +449 -0
  6. package/dist/demo/testScheme.d.ts +56 -0
  7. package/dist/demo/testScheme.js +42 -0
  8. package/dist/form/CreateUpdate.svelte +219 -0
  9. package/dist/{demo/form → form}/CreateUpdate.svelte.d.ts +5 -7
  10. package/dist/form/DataProvider.svelte +23 -0
  11. package/dist/form/DataProvider.svelte.d.ts +7 -0
  12. package/dist/form/FieldInPlace.svelte +98 -0
  13. package/dist/form/FieldInPlace.svelte.d.ts +14 -0
  14. package/dist/form/FieldValue.svelte +148 -0
  15. package/dist/{demo/form → form}/FieldValue.svelte.d.ts +8 -9
  16. package/dist/fragments/Confirm.svelte +73 -58
  17. package/dist/fragments/Confirm.svelte.d.ts +4 -8
  18. package/dist/fragments/Frame.svelte +19 -19
  19. package/dist/fragments/InfoLine.svelte +21 -21
  20. package/dist/fragments/Selector.svelte +26 -26
  21. package/dist/fragments/Skeleton.svelte +21 -21
  22. package/dist/index.d.ts +22 -30
  23. package/dist/index.js +22 -30
  24. package/dist/main/machine/MachineError.d.ts +33 -0
  25. package/dist/main/machine/MachineError.js +49 -0
  26. package/dist/main/machine/MachineErrorValidation.d.ts +19 -0
  27. package/dist/main/machine/MachineErrorValidation.js +24 -0
  28. package/dist/main/machine/MachineFieldType.d.ts +121 -0
  29. package/dist/main/machine/MachineFieldType.js +250 -0
  30. package/dist/main/machine/MachineScheme.d.ts +84 -0
  31. package/dist/main/machine/MachineScheme.js +146 -0
  32. package/dist/main/machine/MachineSchemeField.d.ts +19 -0
  33. package/dist/main/machine/MachineSchemeField.js +51 -0
  34. package/dist/main/machine/MachineSchemeFieldForge.d.ts +84 -0
  35. package/dist/main/machine/MachineSchemeFieldForge.js +128 -0
  36. package/dist/main/machine/MachineSchemeFieldValues.d.ts +69 -0
  37. package/dist/main/machine/MachineSchemeFieldValues.js +94 -0
  38. package/dist/main/machine/MachineSchemeValidate.d.ts +51 -0
  39. package/dist/main/machine/MachineSchemeValidate.js +120 -0
  40. package/dist/main/machine/MachineSchemeValues.d.ts +109 -0
  41. package/dist/main/machine/{IDbCollectionValues.js → MachineSchemeValues.js} +116 -41
  42. package/dist/main/machine/SchemeFieldDefaultValues.d.ts +74 -0
  43. package/dist/main/machine/SchemeFieldDefaultValues.js +98 -0
  44. package/dist/main/machine.d.ts +71 -44
  45. package/dist/main/machine.js +74 -43
  46. package/dist/main/machineDb.d.ts +14 -56
  47. package/dist/main/machineDb.js +15 -98
  48. package/dist/main/{machineForge.d.ts → machineParserForge.d.ts} +15 -25
  49. package/dist/main/{machineForge.js → machineParserForge.js} +16 -10
  50. package/dist/ui/CollectionButton.svelte +29 -26
  51. package/dist/ui/CollectionButton.svelte.d.ts +3 -3
  52. package/dist/ui/CollectionFks.svelte +24 -24
  53. package/dist/ui/CollectionFks.svelte.d.ts +2 -2
  54. package/dist/ui/CollectionList.svelte +100 -95
  55. package/dist/ui/CollectionList.svelte.d.ts +1 -2
  56. package/dist/ui/CollectionListFieldValues.svelte +59 -0
  57. package/dist/ui/CollectionListFieldValues.svelte.d.ts +9 -0
  58. package/dist/ui/CollectionListMenu.svelte +39 -47
  59. package/dist/ui/CollectionListMenu.svelte.d.ts +1 -1
  60. package/dist/ui/CollectionReverseFks.svelte +37 -56
  61. package/dist/ui/CollectionReverseFks.svelte.d.ts +4 -8
  62. package/package.json +18 -5
  63. package/dist/db/dbSchema.d.ts +0 -201
  64. package/dist/db/dbSchema.js +0 -205
  65. package/dist/db/fieldTypes.d.ts +0 -13
  66. package/dist/db/fieldTypes.js +0 -67
  67. package/dist/db/types.d.ts +0 -124
  68. package/dist/demo/form/CreateUpdate.svelte +0 -198
  69. package/dist/demo/form/CrudZone.svelte +0 -22
  70. package/dist/demo/form/CrudZone.svelte.d.ts +0 -29
  71. package/dist/demo/form/DataProvider.svelte +0 -20
  72. package/dist/demo/form/DataProvider.svelte.d.ts +0 -9
  73. package/dist/demo/form/FieldInPlace.svelte +0 -49
  74. package/dist/demo/form/FieldInPlace.svelte.d.ts +0 -11
  75. package/dist/demo/form/FieldValue.svelte +0 -212
  76. package/dist/demo/form/types.js +0 -1
  77. package/dist/demo/testDbSchema.d.ts +0 -6
  78. package/dist/demo/testDbSchema.js +0 -58
  79. package/dist/demo/types.d.ts +0 -140
  80. package/dist/demo/types.js +0 -1
  81. package/dist/fragments/List.svelte +0 -21
  82. package/dist/fragments/List.svelte.d.ts +0 -38
  83. package/dist/main/machine/IDbCollection.d.ts +0 -69
  84. package/dist/main/machine/IDbCollection.js +0 -98
  85. package/dist/main/machine/IDbCollectionFieldForge.d.ts +0 -42
  86. package/dist/main/machine/IDbCollectionFieldForge.js +0 -74
  87. package/dist/main/machine/IDbCollectionFieldValues.d.ts +0 -46
  88. package/dist/main/machine/IDbCollectionFieldValues.js +0 -62
  89. package/dist/main/machine/IDbCollectionValues.d.ts +0 -78
  90. package/dist/main/machine/IDbError.d.ts +0 -6
  91. package/dist/main/machine/IDbError.js +0 -61
  92. package/dist/main/machine/IDbFormValidate.d.ts +0 -55
  93. package/dist/main/machine/IDbFormValidate.js +0 -183
  94. package/dist/main/machine/IDbValidationError.d.ts +0 -19
  95. package/dist/main/machine/IDbValidationError.js +0 -24
  96. package/dist/main/machine/types.d.ts +0 -1
  97. package/dist/main/machine/types.js +0 -1
  98. package/dist/ui/CollectionFieldGuess.svelte +0 -29
  99. package/dist/ui/CollectionFieldGuess.svelte.d.ts +0 -11
  100. /package/dist/{demo/form → form}/types.d.ts +0 -0
  101. /package/dist/{db → form}/types.js +0 -0
@@ -1,51 +1,43 @@
1
1
  import { MachineDb } from '../machineDb.js';
2
- import {} from '../machineForge.js';
3
- import { IDbError } from './IDbError.js';
2
+ import { MachineError } from './MachineError.js';
3
+ import { SchemeFieldDefaultValues } from './SchemeFieldDefaultValues.js';
4
4
  /**
5
- * IDbCollectionValues
6
- *
7
- * This class provides utilities to display, format, and introspect field values for a given collection, using the schema and provided data.
8
- * It is designed for dynamic UI rendering, presentation logic, and metadata extraction for form generation in schema-driven applications.
9
- *
10
- * Main responsibilities:
11
- * - Holds a reference to the collection name and the schema (IDbBase).
12
- * - Provides methods to format field values according to their type (number, text, array, object, etc.).
13
- * - Supplies presentation logic for displaying records (e.g., presentation string, index value).
14
- * - Offers input attribute generation for forms (inputDataSet).
15
- * - Supports iteration over array/object fields for advanced UI layouts.
16
- * - Enables access to field metadata for validation and rendering.
17
- *
18
- * Usage:
19
- * const values = new IDbCollectionValues('agents');
20
- * const display = values.presentation(agentData); // formatted display string
21
- * const index = values.indexValue(agentData); // index field value
22
- * const formatted = values.format('name', agentData); // formatted field value
23
- * const attrs = values.getInputDataSet('name', agentData); // input attributes for forms
5
+ * @class MachineSchemeValues
6
+ * @role Provides utilities to display, format, and introspect field values for a given collection, using the schema and provided data.
24
7
  *
25
8
  * This class is typically used via IDbBase.getCollectionValues for shared instance management.
26
- * @template T - The type of the data object for the collection.
9
+ *
10
+ * @template T The type of the data object for the collection.
27
11
  */
28
- export class IDbCollectionValues {
12
+ export class MachineSchemeValues {
29
13
  /**
30
14
  * The IDbBase instance used for schema introspection.
31
15
  */
32
- idbBase;
16
+ machine;
33
17
  /**
34
18
  * The collection name this instance operates on.
35
19
  */
36
20
  collectionName;
37
21
  /**
38
22
  * Create a new IDbCollectionValues instance for a given collection.
39
- * @param collectionName The collection name.
23
+ * @role Constructor
24
+ * @param {TplCollectionName} collectionName The collection name.
25
+ * @param {MachineDb} machine The MachineDb instance.
40
26
  */
41
- constructor(collectionName, idbBase) {
27
+ constructor(collectionName, machine) {
42
28
  this.collectionName = collectionName;
43
- this.idbBase = idbBase ?? new MachineDb();
29
+ this.machine = machine;
44
30
  }
31
+ /**
32
+ * Get the presentation string for a data object, using the collection's presentation template.
33
+ * @role Presentation logic
34
+ * @param {Record<string, any>} data The data object.
35
+ * @return {string} The formatted presentation string.
36
+ */
45
37
  presentation(data) {
46
38
  try {
47
39
  this.#checkError(!this.#checkAccess(), 'Access denied', 'ACCESS_DENIED');
48
- const presentation = this.idbBase.collection(this.collectionName).getPresentation();
40
+ const presentation = this.machine.collection(this.collectionName).template.presentation;
49
41
  this.#checkError(!presentation, 'Presentation template not found', 'TEMPLATE_NOT_FOUND');
50
42
  const fields = presentation.split(' ');
51
43
  return fields
@@ -56,7 +48,7 @@ export class IDbCollectionValues {
56
48
  .join(' ');
57
49
  }
58
50
  catch (error) {
59
- IDbError.handleError(error);
51
+ MachineError.handleError(error);
60
52
  return '';
61
53
  }
62
54
  }
@@ -65,16 +57,22 @@ export class IDbCollectionValues {
65
57
  * @param data The data object.
66
58
  * @returns The value of the index field, or null if not found.
67
59
  */
60
+ /**
61
+ * Get the value of the index field for a data object.
62
+ * @role Index accessor
63
+ * @param {Record<string, any>} data The data object.
64
+ * @return {any | null} The value of the index field, or null if not found.
65
+ */
68
66
  indexValue(data) {
69
67
  try {
70
68
  this.#checkError(!this.#checkAccess(), 'Access denied', 'ACCESS_DENIED');
71
- const indexName = this.idbBase.collection(this.collectionName).getIndexName();
69
+ const indexName = this.machine.collection(this.collectionName).template.index;
72
70
  this.#checkError(!indexName, 'Index not found for collection', 'INDEX_NOT_FOUND');
73
71
  this.#checkError(!(indexName in data), `Index field ${indexName} not found in data`, 'FIELD_NOT_FOUND');
74
72
  return data[indexName];
75
73
  }
76
74
  catch (error) {
77
- IDbError.handleError(error);
75
+ MachineError.handleError(error);
78
76
  return null;
79
77
  }
80
78
  }
@@ -84,13 +82,23 @@ export class IDbCollectionValues {
84
82
  * @param data The data object.
85
83
  * @returns The formatted value as a string.
86
84
  */
85
+ /**
86
+ * Format a field value for display, using the field type and schema.
87
+ * @role Field formatting
88
+ * @param {keyof T} fieldName The field name.
89
+ * @param {T} data The data object.
90
+ * @return {string} The formatted value as a string.
91
+ */
87
92
  format(fieldName, data) {
88
93
  try {
89
94
  this.#checkError(!this.#checkAccess(), 'Access denied', 'ACCESS_DENIED');
90
95
  this.#checkError(!(fieldName in data), `Field ${String(fieldName)} not found in data`, 'FIELD_NOT_FOUND');
91
- const fieldInfo = this.idbBase.parseCollectionFieldName(this.collectionName, fieldName);
96
+ const fieldInfo = this.machine.collection(this.collectionName).field(String(fieldName)).parse();
92
97
  this.#checkError(!fieldInfo, `Field ${String(fieldName)} not found in collection`, 'FIELD_NOT_FOUND');
93
- switch (fieldInfo?.fieldType) {
98
+ if (!fieldInfo) {
99
+ return String(data[fieldName]);
100
+ }
101
+ switch (fieldInfo.fieldType) {
94
102
  case 'number':
95
103
  return this.#formatNumberField(data[fieldName]);
96
104
  case 'text':
@@ -105,7 +113,7 @@ export class IDbCollectionValues {
105
113
  }
106
114
  }
107
115
  catch (error) {
108
- IDbError.handleError(error);
116
+ MachineError.handleError(error);
109
117
  return '';
110
118
  }
111
119
  }
@@ -115,11 +123,18 @@ export class IDbCollectionValues {
115
123
  * @param data The data object.
116
124
  * @returns An object with data-* attributes for the field.
117
125
  */
126
+ /**
127
+ * Get a set of data-* attributes for a field, for use in form generation or UI.
128
+ * @role Input attribute generation
129
+ * @param {string} fieldName The field name.
130
+ * @param {T} data The data object.
131
+ * @return {Record<`data-${'collection' | 'collectionId' | 'fieldName' | 'fieldType' | 'fieldArgs'}`, string>} The data-* attributes for the field.
132
+ */
118
133
  getInputDataSet(fieldName, data) {
119
- const fieldInfo = this.idbBase.parseCollectionFieldName(this.collectionName, fieldName);
134
+ const fieldInfo = this.machine.collection(this.collectionName).field(fieldName).parse();
120
135
  const fieldType = fieldInfo?.fieldType ?? '';
121
136
  const fieldArgs = fieldInfo?.fieldArgs?.join(' ') ?? '';
122
- const indexName = this.idbBase.collection(this.collectionName).getIndexName();
137
+ const indexName = this.machine.collection(this.collectionName).template.index;
123
138
  return {
124
139
  'data-collection': this.collectionName,
125
140
  'data-collectionId': indexName && data?.[indexName] !== undefined ? String(data?.[indexName]) : '',
@@ -134,12 +149,25 @@ export class IDbCollectionValues {
134
149
  * @param data The array data.
135
150
  * @returns An array of IDbForge objects.
136
151
  */
152
+ /**
153
+ * Iterate over an array field and return an array of IDbForge objects for each element.
154
+ * @role Array field iteration
155
+ * @param {keyof TplFields} fieldName The field name.
156
+ * @param {any[]} data The array data.
157
+ * @return {IDbForge[]} An array of IDbForge objects.
158
+ */
159
+ // NOTE: Return type is any[] to match actual runtime type from parser (fieldArgs may be string)
160
+ // TODO: Refine IDbForge type if needed for stricter typing
137
161
  iterateArrayField(fieldName, data) {
138
- const fieldInfo = this.idbBase.parseCollectionFieldName(this.collectionName, fieldName);
162
+ const fieldInfo = this.machine.collection(this.collectionName).field(fieldName).parse();
139
163
  if (fieldInfo?.is !== 'array' || !Array.isArray(data)) {
140
164
  return [];
141
165
  }
142
- return data.map((_, idx) => ({ ...fieldInfo, fieldName: `${String(fieldName)}[${idx}]` }));
166
+ return data
167
+ .map((_, idx) => fieldInfo && fieldInfo.fieldType
168
+ ? { ...fieldInfo, fieldName: `${String(fieldName)}[${idx}]`, collection: this.collectionName }
169
+ : undefined)
170
+ .filter(Boolean);
143
171
  }
144
172
  /**
145
173
  * Iterate over an object field and return an array of IDbForge objects for each property.
@@ -147,18 +175,37 @@ export class IDbCollectionValues {
147
175
  * @param data The object data.
148
176
  * @returns An array of IDbForge objects.
149
177
  */
178
+ /**
179
+ * Iterate over an object field and return an array of IDbForge objects for each property.
180
+ * @role Object field iteration
181
+ * @param {keyof TplFields} fieldName The field name.
182
+ * @param {Record<string, unknown>} data The object data.
183
+ * @return {IDbForge[]} An array of IDbForge objects.
184
+ */
185
+ // NOTE: Return type is any[] to match actual runtime type from parser (fieldArgs may be string)
186
+ // TODO: Refine IDbForge type if needed for stricter typing
150
187
  iterateObjectField(fieldName, data) {
151
- const fieldInfo = this.idbBase.parseCollectionFieldName(this.collectionName, fieldName);
188
+ const fieldInfo = this.machine.collection(this.collectionName).field(fieldName).parse();
152
189
  if (fieldInfo?.is !== 'object' || typeof data !== 'object' || data === null) {
153
190
  return [];
154
191
  }
155
- return Object.keys(data).map((key) => ({ ...fieldInfo, fieldName: `${String(fieldName)}.${key}` }));
192
+ return Object.keys(data)
193
+ .map((key) => fieldInfo && fieldInfo.fieldType
194
+ ? { ...fieldInfo, fieldName: `${String(fieldName)}.${key}`, collection: this.collectionName }
195
+ : undefined)
196
+ .filter(Boolean);
156
197
  }
157
198
  /**
158
199
  * Internal: Format a number field for display.
159
200
  * @param value The number value.
160
201
  * @returns The formatted string.
161
202
  */
203
+ /**
204
+ * Internal: Format a number field for display.
205
+ * @role Number formatting
206
+ * @param {number} value The number value.
207
+ * @return {string} The formatted string.
208
+ */
162
209
  #formatNumberField(value) {
163
210
  // Implement number formatting logic here
164
211
  return value.toString();
@@ -169,6 +216,13 @@ export class IDbCollectionValues {
169
216
  * @param type The text type (e.g. 'text-short').
170
217
  * @returns The formatted string.
171
218
  */
219
+ /**
220
+ * Internal: Format a text field for display, with length limits by type.
221
+ * @role Text formatting
222
+ * @param {unknown} value The string value.
223
+ * @param {string} type The text type (e.g. 'text-short').
224
+ * @return {string} The formatted string.
225
+ */
172
226
  #formatTextField(value, type) {
173
227
  const lengths = {
174
228
  'text-tiny': 10,
@@ -185,6 +239,11 @@ export class IDbCollectionValues {
185
239
  * Internal: Check if access is allowed (override for custom logic).
186
240
  * @returns True if access is allowed.
187
241
  */
242
+ /**
243
+ * Internal: Check if access is allowed (override for custom logic).
244
+ * @role Access check
245
+ * @return {boolean} True if access is allowed.
246
+ */
188
247
  #checkAccess() {
189
248
  // Implement access check logic here
190
249
  return true;
@@ -195,9 +254,25 @@ export class IDbCollectionValues {
195
254
  * @param message The error message.
196
255
  * @param code The error code.
197
256
  */
257
+ /**
258
+ * Internal: Throw an error if a condition is met.
259
+ * @role Error handling
260
+ * @param {boolean} condition The condition to check.
261
+ * @param {string} message The error message.
262
+ * @param {string} code The error code.
263
+ */
198
264
  #checkError(condition, message, code) {
199
265
  if (condition) {
200
- IDbError.throwError(message, code);
266
+ MachineError.throwError(message, code);
201
267
  }
202
268
  }
269
+ /**
270
+ * Get default values for the collection, using global and collection-specific factories.
271
+ * @role Default values
272
+ * @returns {Record<string, any>} An object with default values for each field in the collection.
273
+ */
274
+ getDefaults() {
275
+ const fields = Object.keys(this.machine.collection(this.collectionName).template.fields || {});
276
+ return SchemeFieldDefaultValues.getDefaults(fields, this.collectionName);
277
+ }
203
278
  }
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Example: Using SchemeFieldDefaultValues to get default values for a collection
3
+ *
4
+ * import { SchemeFieldDefaultValues } from './SchemeFieldDefaultValues';
5
+ *
6
+ * // For a collection 'agents' with fields ['name', 'role', 'createdAt']
7
+ * const defaults = SchemeFieldDefaultValues.getDefaults(['name', 'role', 'createdAt'], 'agents');
8
+ * // defaults = { name: ..., role: ..., createdAt: ... }
9
+ *
10
+ * // In a Svelte form (pseudo-code):
11
+ * let formData = { ...SchemeFieldDefaultValues.getDefaults(Object.keys(formFields), collection) };
12
+ *
13
+ * // When rendering the form, fields with no user value will use the default
14
+ * <input name="name" bind:value={formData.name} />
15
+ * <input name="role" bind:value={formData.role} />
16
+ * <input name="createdAt" bind:value={formData.createdAt} />
17
+ *
18
+ * // To set or override a default globally:
19
+ * SchemeFieldDefaultValues.setDefault('role', () => 'admin');
20
+ *
21
+ * // To set a default for a specific collection:
22
+ * SchemeFieldDefaultValues.setDefault('role', () => 'user', 'agents');
23
+ *
24
+ * // To set multiple defaults at once:
25
+ * SchemeFieldDefaultValues.setDefaults({ status: () => 'active', country: () => 'FR' });
26
+ *
27
+ * // To set multiple defaults for a collection:
28
+ * SchemeFieldDefaultValues.setDefaults({ status: () => 'pending' }, 'orders');
29
+ */
30
+ import type { TplCollectionName } from "@medyll/idae-idbql";
31
+ export declare class SchemeFieldDefaultValues {
32
+ /**
33
+ * Default value factories for all collections (global fields).
34
+ * Each key is a field name, value is a function returning the default value.
35
+ * @type {Record<string, () => any>}
36
+ */
37
+ static defaultFieldFactories: Record<string, () => any>;
38
+ /**
39
+ * Default value factories per collection.
40
+ * Each key is a collection name, value is an object of field factories.
41
+ * @type {Record<string, Record<string, () => any>>}
42
+ */
43
+ static defaultCollectionFactories: Record<string, Record<string, () => any>>;
44
+ /**
45
+ * Add or update a default value factory for a single field (global or collection-specific).
46
+ * @param {string} field - The field name.
47
+ * @param {() => any} factory - The factory function.
48
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific default.
49
+ */
50
+ static setDefault(field: string, factory: () => any, collectionName?: TplCollectionName): void;
51
+ /**
52
+ * Add or update multiple default value factories at once (global or collection-specific).
53
+ * @param {Record<string, () => any>} factories - Object of field:factory pairs.
54
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific defaults.
55
+ */
56
+ static setDefaults(factories: Record<string, () => any>, collectionName?: TplCollectionName): void;
57
+ /**
58
+ * Get default values for a set of fields, using global and optionally collection-specific factories.
59
+ * If collectionName is provided, collection-specific factories take priority over global ones.
60
+ * If not, only global defaults are used.
61
+ *
62
+ * @param {string[]} fields - The list of field names.
63
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific defaults.
64
+ * @returns {Record<string, any>} An object with default values for each field.
65
+ */
66
+ static getDefaults(fields: string[], collectionName?: TplCollectionName): Record<string, any>;
67
+ /**
68
+ * Get the default value for a single field, using collection-specific or global factory.
69
+ * @param {string} field - The field name.
70
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific default.
71
+ * @returns {any} The default value for the field, or undefined if none.
72
+ */
73
+ static getDefault(field: string, collectionName?: TplCollectionName): any;
74
+ }
@@ -0,0 +1,98 @@
1
+ // Example: How to use SchemeFieldDefaultValues in a Svelte form
2
+ // (for documentation/demo, not for direct import)
3
+ // Single class declaration with all static methods and properties
4
+ export class SchemeFieldDefaultValues {
5
+ /**
6
+ * Default value factories for all collections (global fields).
7
+ * Each key is a field name, value is a function returning the default value.
8
+ * @type {Record<string, () => any>}
9
+ */
10
+ static defaultFieldFactories = {
11
+ createdAt: () => new Date(),
12
+ updatedAt: () => new Date(),
13
+ status: () => "draft",
14
+ // Add more global defaults here
15
+ };
16
+ /**
17
+ * Default value factories per collection.
18
+ * Each key is a collection name, value is an object of field factories.
19
+ * @type {Record<string, Record<string, () => any>>}
20
+ */
21
+ static defaultCollectionFactories = {
22
+ // Example:
23
+ // agents: {
24
+ // role: () => "user",
25
+ // },
26
+ };
27
+ /**
28
+ * Add or update a default value factory for a single field (global or collection-specific).
29
+ * @param {string} field - The field name.
30
+ * @param {() => any} factory - The factory function.
31
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific default.
32
+ */
33
+ static setDefault(field, factory, collectionName) {
34
+ if (collectionName) {
35
+ if (!this.defaultCollectionFactories[collectionName]) {
36
+ this.defaultCollectionFactories[collectionName] = {};
37
+ }
38
+ this.defaultCollectionFactories[collectionName][field] = factory;
39
+ }
40
+ else {
41
+ this.defaultFieldFactories[field] = factory;
42
+ }
43
+ }
44
+ /**
45
+ * Add or update multiple default value factories at once (global or collection-specific).
46
+ * @param {Record<string, () => any>} factories - Object of field:factory pairs.
47
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific defaults.
48
+ */
49
+ static setDefaults(factories, collectionName) {
50
+ if (collectionName) {
51
+ if (!this.defaultCollectionFactories[collectionName]) {
52
+ this.defaultCollectionFactories[collectionName] = {};
53
+ }
54
+ Object.assign(this.defaultCollectionFactories[collectionName], factories);
55
+ }
56
+ else {
57
+ Object.assign(this.defaultFieldFactories, factories);
58
+ }
59
+ }
60
+ /**
61
+ * Get default values for a set of fields, using global and optionally collection-specific factories.
62
+ * If collectionName is provided, collection-specific factories take priority over global ones.
63
+ * If not, only global defaults are used.
64
+ *
65
+ * @param {string[]} fields - The list of field names.
66
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific defaults.
67
+ * @returns {Record<string, any>} An object with default values for each field.
68
+ */
69
+ static getDefaults(fields, collectionName) {
70
+ const result = {};
71
+ const collectionDefaults = collectionName ? (this.defaultCollectionFactories[collectionName] || {}) : {};
72
+ for (const field of fields) {
73
+ if (collectionDefaults[field]) {
74
+ result[field] = collectionDefaults[field]();
75
+ }
76
+ else if (this.defaultFieldFactories[field]) {
77
+ result[field] = this.defaultFieldFactories[field]();
78
+ }
79
+ // else: no default
80
+ }
81
+ return result;
82
+ }
83
+ /**
84
+ * Get the default value for a single field, using collection-specific or global factory.
85
+ * @param {string} field - The field name.
86
+ * @param {TplCollectionName} [collectionName] - Optional collection name for specific default.
87
+ * @returns {any} The default value for the field, or undefined if none.
88
+ */
89
+ static getDefault(field, collectionName) {
90
+ if (collectionName && this.defaultCollectionFactories[collectionName]?.[field]) {
91
+ return this.defaultCollectionFactories[collectionName][field]();
92
+ }
93
+ if (this.defaultFieldFactories[field]) {
94
+ return this.defaultFieldFactories[field]();
95
+ }
96
+ return undefined;
97
+ }
98
+ }
@@ -1,33 +1,8 @@
1
+ import { MachineDb } from "./machineDb.js";
2
+ import { createIdbqDb, type IdbqModel } from "@medyll/idae-idbql";
1
3
  /**
2
- * Example usage:
3
- *
4
- * import { Machine } from './machine.js';
5
- *
6
- * // Create a new Machine instance with default parameters
7
- * const machine = new Machine( 'example-db', 1, { collections: {} });
8
- *
9
- * // Start the machine (initialize collections and IDBQL connection)
10
- * machine.start();
11
- *
12
- * // Access collections (schema logic)
13
- * const collections = machine.collections;
14
- *
15
- * // Access IDBQL (readonly)
16
- * const idbql = machine.idbql;
17
- *
18
- * // Access IDBQL (stateful)
19
- * const idbqlState = machine.idbqlState;
20
- *
21
- * // Access IndexedDB core
22
- * const db = machine.indexedb;
23
- *
24
- * // Access the IDBQL data model
25
- * const model = machine.idbqModel;
26
- */
27
- import { MachineDb } from './machineDb.js';
28
- import { createIdbqDb, type IdbqModel } from '@medyll/idae-idbql';
29
- /**
30
- * Machine: main entry point for managing the IDBQL connection and centralized data access.
4
+ * @class Machine
5
+ * @role Main entry point for managing the IDBQL connection and centralized data access.
31
6
  */
32
7
  export declare class Machine {
33
8
  /**
@@ -49,7 +24,7 @@ export declare class Machine {
49
24
  /**
50
25
  * Centralized access to schema and collection logic
51
26
  */
52
- _idbbase: MachineDb;
27
+ _machineDb: MachineDb;
53
28
  /**
54
29
  * Database name
55
30
  */
@@ -64,43 +39,95 @@ export declare class Machine {
64
39
  _model: IdbqModel;
65
40
  /**
66
41
  * Main constructor
42
+ * @role Constructor
43
+ * @param {string=} dbName The name of the database.
44
+ * @param {number=} version The schema version number.
45
+ * @param {IdbqModel=} model The IDBQL data model.
67
46
  */
68
47
  constructor(dbName?: string, version?: number, model?: IdbqModel);
48
+ /**
49
+ * Initialize the machine with configuration parameters.
50
+ * @role Initializer
51
+ * @param {{ dbName?: string; version?: number; model: IdbqModel }} [options] Optional parameters to set dbName, version, and model.
52
+ * @return {void}
53
+ */
69
54
  init(options?: {
70
55
  dbName?: string;
71
56
  version?: number;
72
- model?: IdbqModel;
57
+ model: IdbqModel;
73
58
  }): void;
74
59
  /**
75
- * Start the machine: initialize collections and IDBQL connection.
60
+ * Start the machine: initializes collections and the IDBQL connection.
61
+ * Call this after constructing the Machine to set up the database and collections.
62
+ * @role Initializer
63
+ * @return {void}
76
64
  */
77
65
  start(): void;
66
+ /**
67
+ * Internal: Creates the collections logic using the provided data model.
68
+ * Throws an error if the model is not defined.
69
+ * @role Internal
70
+ * @private
71
+ * @return {void}
72
+ */
78
73
  private createCollections;
74
+ /**
75
+ * Internal: Creates the IDBQL store and initializes database connections.
76
+ * Throws an error if model, dbName, or version is missing.
77
+ * @role Internal
78
+ * @private
79
+ * @return {void}
80
+ */
79
81
  private createStore;
80
82
  /**
81
- * Get the IDbBase (schema logic) instance
83
+ * Get the MachineDb (schema logic) instance.
84
+ * @role Accessor
85
+ * @deprecated Use logic instead.
86
+ * @return {MachineDb} The schema and collection logic instance.
82
87
  */
83
88
  get collections(): MachineDb;
84
89
  /**
85
- * IDBQL (readonly) instance
90
+ * Get the IDbBase (schema logic) instance.
91
+ * Recommended accessor for schema and collection logic.
92
+ * @role Accessor
93
+ * @return {MachineDb} The schema and collection logic instance.
94
+ */
95
+ get logic(): MachineDb;
96
+ /**
97
+ * Get the IDBQL (readonly) instance.
98
+ * Use for read-only access to collections.
99
+ * @role Accessor
100
+ * @return {ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbql"] | undefined} The readonly IDBQL instance.
86
101
  */
87
- get idbql(): import("@medyll/idae-idbql").ReadonlyCollections<IdbqModel<Record<string, Record<string, any>>>> | undefined;
102
+ get idbql(): ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbql"] | undefined;
88
103
  /**
89
- * IDBQL (stateful) instance , old name was idbqlState => store
104
+ * Get the IDBQL (stateful) instance.
105
+ * Previously called idbqlState; use for stateful operations.
106
+ * @role Accessor
107
+ * @return {ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbqlState"]} The stateful IDBQL instance.
90
108
  */
91
- get store(): import("@medyll/idae-idbql").StateCollections<IdbqModel<Record<string, Record<string, any>>>>;
109
+ get store(): ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbqlState"];
92
110
  /**
93
- * Direct getter for idbqlState (for test compatibility)
111
+ * Direct getter for idbqlState (for test compatibility).
112
+ * Returns the stateful IDBQL instance.
113
+ * @role Accessor
114
+ * @deprecated Use store instead.
115
+ * @return {ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbqlState"]} The stateful IDBQL instance.
94
116
  */
95
- get idbqlState(): import("@medyll/idae-idbql").StateCollections<IdbqModel<Record<string, Record<string, any>>>>;
117
+ get idbqlState(): ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbqlState"];
96
118
  /**
97
- * IndexedDB (core) instance
98
- * @deprecated
119
+ * Get the IndexedDB (core) instance.
120
+ * @role Accessor
121
+ * @deprecated Use IDBQL accessors instead.
122
+ * @return {ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbDatabase"] | undefined} The IndexedDB instance.
99
123
  */
100
- get indexedb(): import("@medyll/idae-idbql").IdbqlIndexedCore<IdbqModel<Record<string, Record<string, any>>>> | undefined;
124
+ get indexedb(): ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbDatabase"] | undefined;
101
125
  /**
102
- * IDBQL data model instance
126
+ * Get the IDBQL data model instance.
127
+ * Returns the current IDBQL model used by the machine.
128
+ * @role Accessor
129
+ * @return {ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbqModel"] | undefined} The IDBQL model instance.
103
130
  */
104
- get idbqModel(): IdbqModel<Record<string, Record<string, any>>> | undefined;
131
+ get idbqModel(): ReturnType<ReturnType<typeof createIdbqDb>["create"]>["idbqModel"] | undefined;
105
132
  }
106
133
  export declare const machine: Machine;