@nejs/basic-extensions 2.21.0 → 2.22.6

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 (270) hide show
  1. package/.idea/markdown.xml +8 -0
  2. package/.idea/modules.xml +8 -0
  3. package/.idea/ne-basic-extensions.iml +8 -0
  4. package/.idea/vcs.xml +6 -0
  5. package/CODE_STYLE.md +393 -0
  6. package/CODING_PHILOSOPHY.md +36 -0
  7. package/DOCUMENTATION_GUIDELINES.md +221 -0
  8. package/README.md +78 -4
  9. package/dist/@nejs/basic-extensions.bundle.2.22.6.js +25 -0
  10. package/dist/@nejs/basic-extensions.bundle.2.22.6.js.map +7 -0
  11. package/dist/cjs/classes/index.cjs +11129 -0
  12. package/dist/cjs/classes/index.cjs.map +7 -0
  13. package/dist/cjs/index.cjs +15191 -0
  14. package/dist/cjs/index.cjs.map +7 -0
  15. package/dist/cjs/utils/index.cjs +3954 -0
  16. package/dist/cjs/utils/index.cjs.map +7 -0
  17. package/dist/esm/basic-extensions.mjs +25 -0
  18. package/dist/esm/basic-extensions.mjs.map +7 -0
  19. package/package.json +16 -22
  20. package/repl.bootstrap.js +4 -7
  21. package/repl.history +30 -30
  22. package/src/big.int.extension.js +171 -45
  23. package/src/classes/enumeration.js +466 -0
  24. package/src/classes/index.js +5 -1
  25. package/src/index.js +5 -1
  26. package/src/math.extension.js +73 -0
  27. package/src/number.extension.js +18 -0
  28. package/src/regular.expression.extensions.js +0 -35
  29. package/src/utils/toolkit.js +699 -516
  30. package/tests/arrayextensions.test.js +3 -3
  31. package/tests/index.test.js +3 -1
  32. package/tests/newClasses/asyncIterable.test.js +3 -3
  33. package/tests/newClasses/deferred.test.js +3 -3
  34. package/tests/newClasses/descriptor.test.js +3 -3
  35. package/tests/newClasses/iterable.test.js +3 -3
  36. package/tests/newClasses/refmap.test.js +3 -3
  37. package/tests/newClasses/refset.test.js +3 -3
  38. package/tests/objectextensions.test.js +3 -3
  39. package/tests/setextensions.test.js +3 -3
  40. package/tests/stringextensions.test.js +3 -2
  41. package/tests/utils/descriptor.utils.test.js +1 -1
  42. package/tests/utils/toolkit.test.js +429 -163
  43. package/.esdoc.json +0 -9
  44. package/.vscode/settings.json +0 -5
  45. package/bin/build +0 -27
  46. package/bin/clean +0 -14
  47. package/bin/esbuild +0 -91
  48. package/bin/fixup +0 -13
  49. package/bin/repl.basics.js +0 -584
  50. package/bin/repl.signature.js +0 -63
  51. package/bin/version +0 -100
  52. package/dist/@nejs/basic-extensions.bundle.2.21.0.js +0 -25
  53. package/dist/@nejs/basic-extensions.bundle.2.21.0.js.map +0 -7
  54. package/dist/cjs/array.extensions.d.ts +0 -39
  55. package/dist/cjs/array.extensions.js +0 -477
  56. package/dist/cjs/array.extensions.js.map +0 -1
  57. package/dist/cjs/big.int.extension.d.ts +0 -31
  58. package/dist/cjs/big.int.extension.js +0 -165
  59. package/dist/cjs/big.int.extension.js.map +0 -1
  60. package/dist/cjs/classes/asyncIterable.d.ts +0 -126
  61. package/dist/cjs/classes/asyncIterable.js +0 -209
  62. package/dist/cjs/classes/asyncIterable.js.map +0 -1
  63. package/dist/cjs/classes/deferred.d.ts +0 -146
  64. package/dist/cjs/classes/deferred.js +0 -291
  65. package/dist/cjs/classes/deferred.js.map +0 -1
  66. package/dist/cjs/classes/descriptor.d.ts +0 -334
  67. package/dist/cjs/classes/descriptor.js +0 -537
  68. package/dist/cjs/classes/descriptor.js.map +0 -1
  69. package/dist/cjs/classes/enum.d.ts +0 -50
  70. package/dist/cjs/classes/enum.js +0 -405
  71. package/dist/cjs/classes/enum.js.map +0 -1
  72. package/dist/cjs/classes/index.d.ts +0 -15
  73. package/dist/cjs/classes/index.js +0 -63
  74. package/dist/cjs/classes/index.js.map +0 -1
  75. package/dist/cjs/classes/introspector.d.ts +0 -20
  76. package/dist/cjs/classes/introspector.js +0 -130
  77. package/dist/cjs/classes/introspector.js.map +0 -1
  78. package/dist/cjs/classes/iterable.d.ts +0 -169
  79. package/dist/cjs/classes/iterable.js +0 -268
  80. package/dist/cjs/classes/iterable.js.map +0 -1
  81. package/dist/cjs/classes/param.parser.d.ts +0 -221
  82. package/dist/cjs/classes/param.parser.js +0 -242
  83. package/dist/cjs/classes/param.parser.js.map +0 -1
  84. package/dist/cjs/classes/pluggable.proxy.d.ts +0 -153
  85. package/dist/cjs/classes/pluggable.proxy.js +0 -444
  86. package/dist/cjs/classes/pluggable.proxy.js.map +0 -1
  87. package/dist/cjs/classes/property.d.ts +0 -79
  88. package/dist/cjs/classes/property.js +0 -284
  89. package/dist/cjs/classes/property.js.map +0 -1
  90. package/dist/cjs/classes/refmap.d.ts +0 -238
  91. package/dist/cjs/classes/refmap.js +0 -421
  92. package/dist/cjs/classes/refmap.js.map +0 -1
  93. package/dist/cjs/classes/refset.d.ts +0 -186
  94. package/dist/cjs/classes/refset.js +0 -370
  95. package/dist/cjs/classes/refset.js.map +0 -1
  96. package/dist/cjs/classes/symkeys.d.ts +0 -349
  97. package/dist/cjs/classes/symkeys.js +0 -510
  98. package/dist/cjs/classes/symkeys.js.map +0 -1
  99. package/dist/cjs/classes/type.d.ts +0 -56
  100. package/dist/cjs/classes/type.js +0 -405
  101. package/dist/cjs/classes/type.js.map +0 -1
  102. package/dist/cjs/function.extensions.d.ts +0 -12
  103. package/dist/cjs/function.extensions.js +0 -758
  104. package/dist/cjs/function.extensions.js.map +0 -1
  105. package/dist/cjs/global.this.d.ts +0 -2
  106. package/dist/cjs/global.this.js +0 -300
  107. package/dist/cjs/global.this.js.map +0 -1
  108. package/dist/cjs/index.d.ts +0 -31
  109. package/dist/cjs/index.js +0 -226
  110. package/dist/cjs/index.js.map +0 -1
  111. package/dist/cjs/json.extensions.d.ts +0 -2
  112. package/dist/cjs/json.extensions.js +0 -109
  113. package/dist/cjs/json.extensions.js.map +0 -1
  114. package/dist/cjs/map.extensions.d.ts +0 -3
  115. package/dist/cjs/map.extensions.js +0 -143
  116. package/dist/cjs/map.extensions.js.map +0 -1
  117. package/dist/cjs/number.extension.d.ts +0 -44
  118. package/dist/cjs/number.extension.js +0 -261
  119. package/dist/cjs/number.extension.js.map +0 -1
  120. package/dist/cjs/object.extensions.d.ts +0 -33
  121. package/dist/cjs/object.extensions.js +0 -1091
  122. package/dist/cjs/object.extensions.js.map +0 -1
  123. package/dist/cjs/package.json +0 -3
  124. package/dist/cjs/proxy.extensions.d.ts +0 -2
  125. package/dist/cjs/proxy.extensions.js +0 -207
  126. package/dist/cjs/proxy.extensions.js.map +0 -1
  127. package/dist/cjs/reflect.extensions.d.ts +0 -14
  128. package/dist/cjs/reflect.extensions.js +0 -316
  129. package/dist/cjs/reflect.extensions.js.map +0 -1
  130. package/dist/cjs/regular.expression.extensions.d.ts +0 -2
  131. package/dist/cjs/regular.expression.extensions.js +0 -423
  132. package/dist/cjs/regular.expression.extensions.js.map +0 -1
  133. package/dist/cjs/set.extensions.d.ts +0 -40
  134. package/dist/cjs/set.extensions.js +0 -355
  135. package/dist/cjs/set.extensions.js.map +0 -1
  136. package/dist/cjs/string.extensions.d.ts +0 -23
  137. package/dist/cjs/string.extensions.js +0 -704
  138. package/dist/cjs/string.extensions.js.map +0 -1
  139. package/dist/cjs/symbol.extensions.d.ts +0 -11
  140. package/dist/cjs/symbol.extensions.js +0 -735
  141. package/dist/cjs/symbol.extensions.js.map +0 -1
  142. package/dist/cjs/utils/copy.object.d.ts +0 -408
  143. package/dist/cjs/utils/copy.object.js +0 -720
  144. package/dist/cjs/utils/copy.object.js.map +0 -1
  145. package/dist/cjs/utils/descriptor.utils.d.ts +0 -298
  146. package/dist/cjs/utils/descriptor.utils.js +0 -889
  147. package/dist/cjs/utils/descriptor.utils.js.map +0 -1
  148. package/dist/cjs/utils/index.d.ts +0 -75
  149. package/dist/cjs/utils/index.js +0 -61
  150. package/dist/cjs/utils/index.js.map +0 -1
  151. package/dist/cjs/utils/stdout.d.ts +0 -742
  152. package/dist/cjs/utils/stdout.js +0 -1042
  153. package/dist/cjs/utils/stdout.js.map +0 -1
  154. package/dist/cjs/utils/toolkit.d.ts +0 -1898
  155. package/dist/cjs/utils/toolkit.js +0 -1378
  156. package/dist/cjs/utils/toolkit.js.map +0 -1
  157. package/dist/cjs/weakref.extensions.d.ts +0 -2
  158. package/dist/cjs/weakref.extensions.js +0 -19
  159. package/dist/cjs/weakref.extensions.js.map +0 -1
  160. package/dist/mjs/array.extensions.d.ts +0 -39
  161. package/dist/mjs/array.extensions.js +0 -474
  162. package/dist/mjs/array.extensions.js.map +0 -1
  163. package/dist/mjs/big.int.extension.d.ts +0 -31
  164. package/dist/mjs/big.int.extension.js +0 -162
  165. package/dist/mjs/big.int.extension.js.map +0 -1
  166. package/dist/mjs/classes/asyncIterable.d.ts +0 -126
  167. package/dist/mjs/classes/asyncIterable.js +0 -204
  168. package/dist/mjs/classes/asyncIterable.js.map +0 -1
  169. package/dist/mjs/classes/deferred.d.ts +0 -146
  170. package/dist/mjs/classes/deferred.js +0 -287
  171. package/dist/mjs/classes/deferred.js.map +0 -1
  172. package/dist/mjs/classes/descriptor.d.ts +0 -334
  173. package/dist/mjs/classes/descriptor.js +0 -533
  174. package/dist/mjs/classes/descriptor.js.map +0 -1
  175. package/dist/mjs/classes/enum.d.ts +0 -50
  176. package/dist/mjs/classes/enum.js +0 -400
  177. package/dist/mjs/classes/enum.js.map +0 -1
  178. package/dist/mjs/classes/index.d.ts +0 -15
  179. package/dist/mjs/classes/index.js +0 -46
  180. package/dist/mjs/classes/index.js.map +0 -1
  181. package/dist/mjs/classes/introspector.d.ts +0 -20
  182. package/dist/mjs/classes/introspector.js +0 -126
  183. package/dist/mjs/classes/introspector.js.map +0 -1
  184. package/dist/mjs/classes/iterable.d.ts +0 -169
  185. package/dist/mjs/classes/iterable.js +0 -263
  186. package/dist/mjs/classes/iterable.js.map +0 -1
  187. package/dist/mjs/classes/param.parser.d.ts +0 -221
  188. package/dist/mjs/classes/param.parser.js +0 -238
  189. package/dist/mjs/classes/param.parser.js.map +0 -1
  190. package/dist/mjs/classes/pluggable.proxy.d.ts +0 -153
  191. package/dist/mjs/classes/pluggable.proxy.js +0 -438
  192. package/dist/mjs/classes/pluggable.proxy.js.map +0 -1
  193. package/dist/mjs/classes/property.d.ts +0 -79
  194. package/dist/mjs/classes/property.js +0 -280
  195. package/dist/mjs/classes/property.js.map +0 -1
  196. package/dist/mjs/classes/refmap.d.ts +0 -238
  197. package/dist/mjs/classes/refmap.js +0 -417
  198. package/dist/mjs/classes/refmap.js.map +0 -1
  199. package/dist/mjs/classes/refset.d.ts +0 -186
  200. package/dist/mjs/classes/refset.js +0 -366
  201. package/dist/mjs/classes/refset.js.map +0 -1
  202. package/dist/mjs/classes/symkeys.d.ts +0 -349
  203. package/dist/mjs/classes/symkeys.js +0 -506
  204. package/dist/mjs/classes/symkeys.js.map +0 -1
  205. package/dist/mjs/classes/type.d.ts +0 -56
  206. package/dist/mjs/classes/type.js +0 -401
  207. package/dist/mjs/classes/type.js.map +0 -1
  208. package/dist/mjs/function.extensions.d.ts +0 -12
  209. package/dist/mjs/function.extensions.js +0 -755
  210. package/dist/mjs/function.extensions.js.map +0 -1
  211. package/dist/mjs/global.this.d.ts +0 -2
  212. package/dist/mjs/global.this.js +0 -264
  213. package/dist/mjs/global.this.js.map +0 -1
  214. package/dist/mjs/index.d.ts +0 -31
  215. package/dist/mjs/index.js +0 -204
  216. package/dist/mjs/index.js.map +0 -1
  217. package/dist/mjs/json.extensions.d.ts +0 -2
  218. package/dist/mjs/json.extensions.js +0 -106
  219. package/dist/mjs/json.extensions.js.map +0 -1
  220. package/dist/mjs/map.extensions.d.ts +0 -3
  221. package/dist/mjs/map.extensions.js +0 -140
  222. package/dist/mjs/map.extensions.js.map +0 -1
  223. package/dist/mjs/number.extension.d.ts +0 -44
  224. package/dist/mjs/number.extension.js +0 -258
  225. package/dist/mjs/number.extension.js.map +0 -1
  226. package/dist/mjs/object.extensions.d.ts +0 -33
  227. package/dist/mjs/object.extensions.js +0 -1088
  228. package/dist/mjs/object.extensions.js.map +0 -1
  229. package/dist/mjs/package.json +0 -3
  230. package/dist/mjs/proxy.extensions.d.ts +0 -2
  231. package/dist/mjs/proxy.extensions.js +0 -204
  232. package/dist/mjs/proxy.extensions.js.map +0 -1
  233. package/dist/mjs/reflect.extensions.d.ts +0 -14
  234. package/dist/mjs/reflect.extensions.js +0 -313
  235. package/dist/mjs/reflect.extensions.js.map +0 -1
  236. package/dist/mjs/regular.expression.extensions.d.ts +0 -2
  237. package/dist/mjs/regular.expression.extensions.js +0 -420
  238. package/dist/mjs/regular.expression.extensions.js.map +0 -1
  239. package/dist/mjs/set.extensions.d.ts +0 -40
  240. package/dist/mjs/set.extensions.js +0 -352
  241. package/dist/mjs/set.extensions.js.map +0 -1
  242. package/dist/mjs/string.extensions.d.ts +0 -23
  243. package/dist/mjs/string.extensions.js +0 -701
  244. package/dist/mjs/string.extensions.js.map +0 -1
  245. package/dist/mjs/symbol.extensions.d.ts +0 -11
  246. package/dist/mjs/symbol.extensions.js +0 -732
  247. package/dist/mjs/symbol.extensions.js.map +0 -1
  248. package/dist/mjs/utils/copy.object.d.ts +0 -408
  249. package/dist/mjs/utils/copy.object.js +0 -702
  250. package/dist/mjs/utils/copy.object.js.map +0 -1
  251. package/dist/mjs/utils/descriptor.utils.d.ts +0 -298
  252. package/dist/mjs/utils/descriptor.utils.js +0 -875
  253. package/dist/mjs/utils/descriptor.utils.js.map +0 -1
  254. package/dist/mjs/utils/index.d.ts +0 -75
  255. package/dist/mjs/utils/index.js +0 -45
  256. package/dist/mjs/utils/index.js.map +0 -1
  257. package/dist/mjs/utils/stdout.d.ts +0 -742
  258. package/dist/mjs/utils/stdout.js +0 -1037
  259. package/dist/mjs/utils/stdout.js.map +0 -1
  260. package/dist/mjs/utils/toolkit.d.ts +0 -1898
  261. package/dist/mjs/utils/toolkit.js +0 -1373
  262. package/dist/mjs/utils/toolkit.js.map +0 -1
  263. package/dist/mjs/weakref.extensions.d.ts +0 -2
  264. package/dist/mjs/weakref.extensions.js +0 -16
  265. package/dist/mjs/weakref.extensions.js.map +0 -1
  266. package/jsdoc-config.json +0 -31
  267. package/tsconfig.base.json +0 -28
  268. package/tsconfig.cjs.json +0 -8
  269. package/tsconfig.esm.json +0 -8
  270. package/vitest.config.js +0 -7
@@ -1,702 +0,0 @@
1
- /**
2
- * Transforms an array into an object using a provided transform
3
- * function.
4
- *
5
- * @function transduceFrom
6
- * @param {Array} array - The array to transform.
7
- * @param {Function} transform - The function used to transform each
8
- * element of the array. It should return an object with 'key' and
9
- * 'value' properties.
10
- * @param {Object} [into={}] - The object to transform the array into.
11
- * @returns {Object} The transformed object.
12
- * @example
13
- * const array = [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
14
- * const transform = (element) => ({ key: element.id, value: element.name })
15
- * transduceFrom(array, transform)
16
- * // => { 1: 'John', 2: 'Jane' }
17
- */
18
- export function tryIgnore(code) {
19
- try {
20
- return code();
21
- }
22
- catch (ignore) {
23
- return undefined;
24
- }
25
- }
26
- export function transduceFrom(array, transform, into = {}) {
27
- if (typeof transform !== 'function') {
28
- return into;
29
- }
30
- return array.reduce((accumulator, element) => {
31
- const { key, value } = (transform?.(element) ?? {});
32
- if (key && value) {
33
- accumulator[key] = value;
34
- }
35
- return accumulator;
36
- }, into);
37
- }
38
- /**
39
- * Transforms a COHandler instance into an object with 'key' and 'value'
40
- * properties.
41
- *
42
- * @function transduceFromCOHandler
43
- * @param {COHandler} element - The COHandler instance to transform.
44
- * @returns {Object} An object with 'key' and 'value' properties, where
45
- * 'key' is the 'property' of the COHandler instance and 'value' is
46
- * the COHandler instance itself.
47
- * @example
48
- * const handler = new COHandler('foo')
49
- * transduceFromCOHandler(handler)
50
- * // => { key: 'foo', value: handler }
51
- */
52
- export function transduceFromCOHandler(element) {
53
- const result = {};
54
- if (element instanceof COPropertyHandler) {
55
- result.key = element.property;
56
- result.value = element;
57
- }
58
- return result;
59
- }
60
- /**
61
- * Creates a transducer function by partially applying the 'array' and
62
- * 'transform' arguments to the 'transduceFrom' function.
63
- *
64
- * @function makeTransducer
65
- * @param {Array} array - The array to transform.
66
- * @param {Function} transform - The function used to transform each
67
- * element of the array.
68
- * @returns {Function} A transducer function that takes an 'into' object
69
- * and returns the result of calling 'transduceFrom' with the provided
70
- * 'array', 'transform', and 'into' arguments.
71
- * @example
72
- * const array = [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
73
- * const transform = (element) => ({ key: element.id, value: element.name })
74
- * const transducer = makeTransducer(array, transform)
75
- * transducer({ 3: 'Jim' })
76
- * // => { 1: 'John', 2: 'Jane', 3: 'Jim' }
77
- */
78
- export function makeTransducer(array, transform) {
79
- return transduceFrom.bind(null, array, transform);
80
- }
81
- /**
82
- * A class for handling property descriptors during object copying.
83
- * @class
84
- * @example
85
- * const handler = new COPropertyHandler('foo', (prop, descriptor) => {
86
- * descriptor.enumerable = false
87
- * return descriptor
88
- * })
89
- * handler.handle('foo', { value: 42, writable: true, enumerable: true })
90
- * // => { value: 42, writable: true, enumerable: false }
91
- */
92
- export class COPropertyHandler {
93
- /**
94
- * The name of the property this handler is responsible for.
95
- * @type {string|undefined}
96
- */
97
- property = undefined;
98
- /**
99
- * The property handler. When provided and invoked, it will receive
100
- * a the property name of the value being handled, the current
101
- * descriptor to transform, and the object into which values are
102
- * currently being copied into.
103
- *
104
- * The result must be a COPropertyHandler response type, which can
105
- * be made with {@link COPropertyHandler.makeResponse} and which
106
- * can be validated with {@link COPropertyHandler.isResponse}.
107
- *
108
- * The handler should have the following parameters
109
- * - {string} property - The name of the property being handled.
110
- * - {Object} curDescriptor - The property descriptor to handle.
111
- * - {Object} destination - The destination object into which
112
- * properties are being copied.
113
- *
114
- * An should return
115
- * - {Object} a `COPropertyHandler.Response` type object which
116
- * can be made with {@link COPropertyHandler.makeResponse}.
117
- *
118
- * @type {function|undefined}
119
- */
120
- handler = undefined;
121
- /**
122
- * Creates a new COPropertyHandler instance.
123
- * @param {string} [property] - The name of the property to handle.
124
- * @param {function} [handler] - The function to handle the property
125
- * descriptor.
126
- */
127
- constructor(property, handler) {
128
- Object.assign(this, { property, handler });
129
- }
130
- /**
131
- * Handles a property descriptor using the registered handler function.
132
- * @param {string} property - The name of the property being handled.
133
- * @param {Object} descriptor - The property descriptor to handle.
134
- * @returns {Object} The resulting property descriptor after handling.
135
- */
136
- handle(property, descriptor, destination) {
137
- if (this.handler) {
138
- return COPropertyHandler.defaultHandle(property, descriptor, this.handler);
139
- }
140
- return descriptor;
141
- }
142
- /**
143
- * The default property descriptor handler.
144
- *
145
- * @param {string} property - The name of the property being handled.
146
- * @param {Object} curDescriptor - The property descriptor to handle.
147
- * @param {Object} destination - The destination object into which
148
- * properties are being copied.
149
- * @param {function} handler - The function to handle the property
150
- * descriptor.
151
- * @returns {Object} a `COPropertyHandler.Response` type object which
152
- * can be made with {@link COPropertyHandler.makeResponse}.
153
- */
154
- static defaultHandle(property, curDescriptor, destination, handler) {
155
- if (typeof handler === 'function') {
156
- try {
157
- const { descriptor, flow } = handler(property, curDescriptor, destination);
158
- return this.makeResponse(descriptor, flow);
159
- }
160
- catch (ignore) { }
161
- }
162
- return this.makeResponse(curDescriptor);
163
- }
164
- /**
165
- * Creates a COPropertyHandler response object.
166
- *
167
- * @param {Object} descriptor - The property descriptor.
168
- * @param {string} [flow=COPropertyHandler.kNoChange] - The flow control
169
- * directive. Must be one of the values from
170
- * {@link COPropertyHandler.flowTypes} if provided.
171
- * @returns {COPropertyHandler.Response} The response object.
172
- * @example
173
- * COPropertyHandler.makeResponse({ value: 42, writable: false })
174
- * // => {
175
- * // newDescriptor: { value: 42, writable: false },
176
- * // flow: 'nochange'
177
- * // }
178
- */
179
- static makeResponse(descriptor, flow) {
180
- return {
181
- newDescriptor: descriptor,
182
- flow: flow ?? this.kNoChange,
183
- get [Symbol.toStringTag]() { return 'COPropertyHandler.Response'; }
184
- };
185
- }
186
- /**
187
- * Checks if a value is a valid COPropertyHandler response object.
188
- * @param {*} value - The value to check.
189
- * @returns {boolean} `true` if the value is a response object, `false`
190
- * otherwise.
191
- * @example
192
- * COPropertyHandler.isResponse({
193
- * newDescriptor: { value: 42 },
194
- * flow: 'nochange'
195
- * })
196
- * // => true
197
- */
198
- static isResponse(value) {
199
- return (value && typeof value === 'object' &&
200
- value[Symbol.toStringTag] === 'COPropertyHandler.Response');
201
- }
202
- /**
203
- * The flow control directive indicating no change in flow.
204
- * @type {string}
205
- */
206
- static get kNoChange() { return 'nochange'; }
207
- /**
208
- * The flow control directive indicating to continue the loop.
209
- * @type {string}
210
- */
211
- static get kContinue() { return 'continue'; }
212
- /**
213
- * The flow control directive indicating to break the loop.
214
- * @type {string}
215
- */
216
- static get kBreak() { return 'break'; }
217
- /**
218
- * An array of all valid flow control directive values.
219
- * @type {string[]}
220
- */
221
- static get flowTypes() {
222
- return [this.kNoChange, this.kContinue, this.kBreak];
223
- }
224
- /**
225
- * An object mapping flow control directive values to their
226
- * corresponding string representations.
227
- * @type {Object.<string, string>}
228
- */
229
- static get flowEnum() {
230
- return {
231
- [this.kNoChange]: this.kNoChange,
232
- [this.kContinue]: this.kContinue,
233
- [this.kBreak]: this.kBreak,
234
- };
235
- }
236
- }
237
- /**
238
- * Returns an object containing getter functions that return Symbol
239
- * values representing different visibility configurations for object
240
- * properties.
241
- *
242
- * @function
243
- * @name kVisibilityKeys
244
- * @returns {Object} An object with the following properties:
245
- * @property {symbol} mutablyHidden - Returns a Symbol representing a
246
- * property that is not enumerable but is configurable.
247
- * @property {symbol} mutablyVisible - Returns a Symbol representing a
248
- * property that is both enumerable and configurable.
249
- * @property {symbol} immutablyHidden - Returns a Symbol representing
250
- * a property that is neither enumerable nor configurable.
251
- * @property {symbol} immutablyVisible - Returns a Symbol representing
252
- * a property that is enumerable but not configurable.
253
- * @property {symbol} flexiblyHidden - Returns a Symbol representing a
254
- * property that is not enumerable, writable and not configurable.
255
- * @property {symbol} flexiblyVisible - Returns a Symbol representing
256
- * a property that is both enumerable and writable, but not
257
- * configurable.
258
- * @property {Generator} keys - Returns a generator that yields the
259
- * string keys of the visibility configurations.
260
- * @property {Generator} symbols - Returns a generator that yields the
261
- * Symbol values of the visibility configurations.
262
- * @property {Generator} entries - Returns a generator that yields
263
- * [key, Symbol] pairs for each visibility configuration.
264
- * @property {Generator} descriptors - Returns a generator that yields
265
- * [key, descriptor] pairs for each visibility configuration, where
266
- * descriptor is the parsed JSON representation of the Symbol's
267
- * description.
268
- * @property {Generator} [Symbol.iterator] - Returns the same generator
269
- * as the symbols property, allowing the object to be iterated over
270
- * directly to access the Symbol values.
271
- *
272
- * @example
273
- * const { mutablyHidden, mutablyVisible } = kVisibilityKeys()
274
- *
275
- * const obj = {
276
- * [mutablyHidden]: 'hidden value',
277
- * [mutablyVisible]: 'visible value',
278
- * }
279
- *
280
- * console.log(obj) // { [Symbol()]: 'visible value' }
281
- * console.log(obj[mutablyHidden]) // 'hidden value'
282
- * console.log(obj[mutablyVisible]) // 'visible value'
283
- *
284
- * @example
285
- * const visibilityKeys = kVisibilityKeys()
286
- *
287
- * for (const key of visibilityKeys.keys()) {
288
- * console.log(key)
289
- * }
290
- * // Output:
291
- * // 'mutablyHidden'
292
- * // 'mutablyVisible'
293
- * // 'immutablyHidden'
294
- * // 'immutablyVisible'
295
- * // 'flexiblyHidden'
296
- * // 'flexiblyVisible'
297
- *
298
- * @example
299
- * const visibilityKeys = kVisibilityKeys()
300
- *
301
- * for (const symbol of visibilityKeys) {
302
- * console.log(symbol)
303
- * }
304
- * // Output:
305
- * // Symbol({"enumerable":false,"configurable":true})
306
- * // Symbol({"enumerable":true,"configurable":true})
307
- * // Symbol({"enumerable":false,"configurable":false})
308
- * // Symbol({"enumerable":true,"configurable":false})
309
- * // Symbol({"enumerable":false,"writable":true})
310
- * // Symbol({"enumerable":true,"writable":true})
311
- */
312
- export function kVisibilityKeys() {
313
- const keys = {
314
- get mutablyHidden() {
315
- return Symbol.for(JSON.stringify({
316
- enumerable: false,
317
- configurable: true,
318
- }));
319
- },
320
- get mutablyVisible() {
321
- return Symbol.for(JSON.stringify({
322
- enumerable: true,
323
- configurable: true,
324
- }));
325
- },
326
- get immutablyHidden() {
327
- return Symbol.for(JSON.stringify({
328
- enumerable: false,
329
- configurable: false,
330
- }));
331
- },
332
- get immutablyVisible() {
333
- return Symbol.for(JSON.stringify({
334
- enumerable: true,
335
- configurable: false,
336
- }));
337
- },
338
- get flexiblyHidden() {
339
- return Symbol.for(JSON.stringify({
340
- enumerable: false,
341
- configurable: false,
342
- writable: true,
343
- }));
344
- },
345
- get flexiblyVisible() {
346
- return Symbol.for(JSON.stringify({
347
- enumerable: true,
348
- configurable: false,
349
- writable: true,
350
- }));
351
- },
352
- };
353
- const enumerated = {
354
- mutablyHidden: keys.mutablyHidden,
355
- mutablyVisible: keys.mutablyVisible,
356
- immutablyHidden: keys.immutablyHidden,
357
- immutablyVisible: keys.immutablyVisible,
358
- flexiblyHidden: keys.flexiblyHidden,
359
- flexiblyVisible: keys.flexiblyVisible,
360
- };
361
- function* keyGenerator() {
362
- for (const key of Object.keys(enumerated)) {
363
- yield key;
364
- }
365
- }
366
- function* symbolGenerator() {
367
- for (const value of Object.values(enumerated)) {
368
- yield value;
369
- }
370
- }
371
- function* entryGenerator() {
372
- for (const entry of Object.entries(enumerated)) {
373
- yield entry;
374
- }
375
- }
376
- function* descriptorGenertor() {
377
- for (const [key, value] of entryGenerator()) {
378
- yield [key, JSON.parse(value.description)];
379
- }
380
- }
381
- Object.defineProperties(keys, {
382
- enumeration: { get() { return enumerated; }, enumerable: false },
383
- keys: { get() { return keyGenerator(); }, enumerable: false },
384
- symbols: { get() { return symbolGenerator(); }, enumerable: false },
385
- entries: { get() { return entryGenerator(); }, enumerable: false },
386
- descriptors: { get() { return descriptorGenertor(); }, enumerable: false },
387
- descriptorFor: {
388
- value(symbol) {
389
- try {
390
- return JSON.parse(symbol.description);
391
- }
392
- catch (ignored) { }
393
- return undefined;
394
- },
395
- enumerable: false
396
- },
397
- [Symbol.iterator]: { get() { return symbolGenerator(); } },
398
- });
399
- return keys;
400
- }
401
- /**
402
- * An object containing Symbol values representing different visibility
403
- * configurations for object properties.
404
- *
405
- * @constant {Object} VisibilityKeys
406
- * @property {symbol} mutablyHidden - A Symbol representing a property
407
- * that is not enumerable but is configurable.
408
- * @property {symbol} mutablyVisible - A Symbol representing a property
409
- * that is both enumerable and configurable.
410
- * @property {symbol} immutablyHidden - A Symbol representing a property
411
- * that is neither enumerable nor configurable.
412
- * @property {symbol} immutablyVisible - A Symbol representing a property
413
- * that is enumerable but not configurable.
414
- * @property {symbol} flexiblyHidden - A Symbol representing a property
415
- * that is not enumerable, writable and not configurable.
416
- * @property {symbol} flexiblyVisible - A Symbol representing a property
417
- * that is both enumerable and writable, but not configurable.
418
- */
419
- export const VisibilityKeys = kVisibilityKeys();
420
- /**
421
- * A class for handling property descriptors during object copying based
422
- * on a specified visibility key.
423
- *
424
- * @class VisibilityScopeHandler
425
- * @extends COPropertyHandler
426
- * @param {symbol} visibilityKey - The visibility key to use for handling
427
- * property descriptors.
428
- * @example
429
- * const handler = new VisibilityScopeHandler(VisibilityKeys.mutablyHidden)
430
- * handler.handle('foo', { value: 42, writable: true, enumerable: true })
431
- * // => { value: 42, writable: true, enumerable: false }
432
- */
433
- export class VisibilityScopeHandler extends COPropertyHandler {
434
- overrides = undefined;
435
- /**
436
- * Creates a new VisibilityScopeHandler instance.
437
- *
438
- * @constructor
439
- * @param {symbol} visibilityKey - The visibility key to use for handling
440
- * property descriptors.
441
- */
442
- constructor(visibilityKey) {
443
- super(visibilityKey, (property, descriptor, dest, source) => {
444
- let data = descriptor?.value;
445
- if (!descriptor || typeof descriptor.value !== 'object') {
446
- return COPropertyHandler.makeResponse(descriptor, 'nochange');
447
- }
448
- if (!data && (descriptor?.get || descriptor?.set)) {
449
- const newDescriptor = this.applyOverridesTo(descriptor);
450
- return COPropertyHandler.makeResponse(newDescriptor, 'nochange');
451
- }
452
- data = customCopyObject({ deep: false }, {}, data ?? {});
453
- this.walkAndApply(data);
454
- descriptor.value = data;
455
- return COPropertyHandler.makeResponse(descriptor, 'continue');
456
- });
457
- tryIgnore(() => this.overrides = JSON.parse(property.description));
458
- }
459
- applyOverridesTo(existingDescriptor, overwrite = false) {
460
- const allowed = ['value', 'get', 'set', 'writable', 'configurable', 'enumerable'];
461
- const output = overwrite ? existingDescriptor : { ...existingDescriptor };
462
- for (let [key, value] of Object.entries(this.overrides ?? {})) {
463
- if (!~allowed.indexOf(key)) {
464
- continue;
465
- }
466
- if (!(['get', 'set'].some(k => k === key) &&
467
- ['undefined', 'function'].some(t => typeof value === t))) {
468
- continue;
469
- }
470
- if (!(['enumerable', 'configurable', 'writable'].some(k => k === key) &&
471
- typeof value !== 'boolean')) {
472
- value = !!value;
473
- }
474
- delete output[key];
475
- output[key] = value;
476
- }
477
- return output;
478
- }
479
- walkAndApply(to) {
480
- Reflect.ownKeys(to).forEach(key => {
481
- tryIgnore(() => {
482
- let result = Object.getOwnPropertyDescriptor(to, key);
483
- this.applyOverridesTo(result, true);
484
- Object.defineProperty(to, key, result);
485
- });
486
- });
487
- }
488
- }
489
- /**
490
- * A handler for mutably visible properties during object copying.
491
- * @class
492
- * @extends VisibilityScopeHandler
493
- * @example
494
- * const handler = new MutablyVisibleHandler()
495
- * const sharedHandler = MutablyVisibleHandler.shared
496
- */
497
- export class MutablyVisibleHandler extends VisibilityScopeHandler {
498
- constructor() { super(VisibilityKeys.mutablyVisible); }
499
- static get shared() {
500
- return this.#singleton ?? (this.#singleton = new this);
501
- }
502
- static #singleton;
503
- }
504
- /**
505
- * A handler for mutably hidden properties during object copying.
506
- * @class
507
- * @extends VisibilityScopeHandler
508
- * @example
509
- * const handler = new MutablyHiddenHandler()
510
- * const sharedHandler = MutablyHiddenHandler.shared
511
- */
512
- export class MutablyHiddenHandler extends VisibilityScopeHandler {
513
- constructor() { super(VisibilityKeys.mutablyHidden); }
514
- static get shared() {
515
- return this.#singleton ?? (this.#singleton = new this);
516
- }
517
- static #singleton;
518
- }
519
- /**
520
- * A handler for immutably visible properties during object copying.
521
- * @class
522
- * @extends VisibilityScopeHandler
523
- * @example
524
- * const handler = new ImmutablyVisibleHandler()
525
- * const sharedHandler = ImmutablyVisibleHandler.shared
526
- */
527
- export class ImmutablyVisibleHandler extends VisibilityScopeHandler {
528
- constructor() { super(VisibilityKeys.immutablyVisible); }
529
- static get shared() {
530
- return this.#singleton ?? (this.#singleton = new this);
531
- }
532
- static #singleton;
533
- }
534
- /**
535
- * A handler for immutably hidden properties during object copying.
536
- * @class
537
- * @extends VisibilityScopeHandler
538
- * @example
539
- * const handler = new ImmutablyHiddenHandler()
540
- * const sharedHandler = ImmutablyHiddenHandler.shared
541
- */
542
- export class ImmutablyHiddenHandler extends VisibilityScopeHandler {
543
- constructor() { super(VisibilityKeys.immutablyHidden); }
544
- static get shared() {
545
- return this.#singleton ?? (this.#singleton = new this);
546
- }
547
- static #singleton;
548
- }
549
- /**
550
- * A handler for flexibly visible properties during object copying.
551
- * @class
552
- * @extends VisibilityScopeHandler
553
- * @example
554
- * const handler = new FlexiblyVisibleHandler()
555
- * const sharedHandler = FlexiblyVisibleHandler.shared
556
- */
557
- export class FlexiblyVisibleHandler extends VisibilityScopeHandler {
558
- constructor() { super(VisibilityKeys.flexiblyVisible); }
559
- static get shared() {
560
- return this.#singleton ?? (this.#singleton = new this);
561
- }
562
- static #singleton;
563
- }
564
- /**
565
- * A handler for flexibly hidden properties during object copying.
566
- * @class
567
- * @extends VisibilityScopeHandler
568
- * @example
569
- * const handler = new FlexiblyHiddenHandler()
570
- * const sharedHandler = FlexiblyHiddenHandler.shared
571
- */
572
- export class FlexiblyHiddenHandler extends VisibilityScopeHandler {
573
- constructor() { super(VisibilityKeys.flexiblyHidden); }
574
- static get shared() {
575
- return this.#singleton ?? (this.#singleton = new this);
576
- }
577
- static #singleton;
578
- }
579
- Object.defineProperties(COPropertyHandler, {
580
- MutablyHiddenHandler: { get() { return MutablyHiddenHandler.shared; } },
581
- MutablyVisibleHandler: { get() { return MutablyVisibleHandler.shared; } },
582
- ImmutablyHiddenHandler: { get() { return ImmutablyHiddenHandler.shared; } },
583
- ImmutablyVisibleHandler: { get() { return ImmutablyVisibleHandler.shared; } },
584
- FlexiblyHiddenHandler: { get() { return FlexiblyHiddenHandler.shared; } },
585
- FlexiblyVisibleHandler: { get() { return FlexiblyVisibleHandler.shared; } },
586
- handlers: {
587
- value: [
588
- MutablyHiddenHandler, MutablyVisibleHandler, ImmutablyHiddenHandler,
589
- ImmutablyVisibleHandler, FlexiblyHiddenHandler, FlexiblyVisibleHandler,
590
- ].map(klass => klass.shared),
591
- configurable: true,
592
- enumerable: true
593
- },
594
- });
595
- /**
596
- * Creates a deep or shallow copy of the provided source objects and merges
597
- * them into the destination object. The function uses a Set to keep track
598
- * of visited objects to avoid circular references.
599
- *
600
- * @function
601
- * @name copyObject
602
- * @param {boolean} deep - If true, performs a deep copy, otherwise performs
603
- * a shallow copy.
604
- * @param {object} destination - The object to which properties will be copied.
605
- * @param {...object} sources - The source object(s) from which properties
606
- * will be copied.
607
- * @returns {object} The destination object with the copied properties.
608
- *
609
- * @example
610
- * // Shallow copy
611
- * const obj1 = { a: 1, b: { c: 2 } };
612
- * const obj2 = { b: { d: 3 }, e: 4 };
613
- * const result = copyObject(false, obj1, obj2);
614
- * console.log(result); // Output: { a: 1, b: { d: 3 }, e: 4 }
615
- *
616
- * @example
617
- * // Deep copy
618
- * const obj1 = { a: 1, b: { c: 2 } };
619
- * const obj2 = { b: { d: 3 }, e: 4 };
620
- * const result = copyObject(true, obj1, obj2);
621
- * console.log(result); // Output: { a: 1, b: { c: 2, d: 3 }, e: 4 }
622
- */
623
- export function copyObject(deep, destination, ...sources) {
624
- const options = {
625
- deep: deep || false,
626
- propertyHandlers: COPropertyHandler?.handlers ?? [],
627
- };
628
- return customCopyObject(options, destination, ...sources);
629
- }
630
- export function customCopyObject(_options, _destination, ..._sources) {
631
- const visited = new Set();
632
- const [options, destination, sources] = ccoParseArgs(_options, _destination, ..._sources);
633
- let { deep } = options;
634
- for (const source of sources) {
635
- if (source === null || typeof source !== 'object' || visited.has(source)) {
636
- continue;
637
- }
638
- visited.add(source);
639
- const keys = Reflect.ownKeys(source);
640
- for (let key of keys) {
641
- let descriptor;
642
- try {
643
- descriptor = Object.getOwnPropertyDescriptor(source, key);
644
- }
645
- catch (err) {
646
- console.warn(`Failed to get descriptor for key "${key}": ${err}`);
647
- continue;
648
- }
649
- const isDataDesc = Reflect.has(descriptor, 'value');
650
- const keyedValue = descriptor?.value;
651
- const conditionsMet = [
652
- isDataDesc,
653
- keyedValue,
654
- typeof keyedValue === 'object',
655
- !visited.has(keyedValue)
656
- ].every(condition => condition);
657
- if (conditionsMet) {
658
- visited.add(keyedValue);
659
- const prototype = Object.getPrototypeOf(keyedValue);
660
- const descriptors = Object.getOwnPropertyDescriptors(keyedValue);
661
- const replacement = Object.create(prototype, descriptors);
662
- descriptor.value = deep
663
- ? customCopyObject(options, replacement, keyedValue)
664
- : replacement;
665
- }
666
- try {
667
- Object.defineProperty(destination, key, descriptor);
668
- }
669
- catch (err) {
670
- console.error(`Failed to define property "${key}": ${err}`);
671
- }
672
- }
673
- }
674
- return destination;
675
- }
676
- function ccoParseArgs(options, destination, ...sources) {
677
- // Parse options
678
- let { deep = true, propertyHandlers = [] } = options;
679
- // Ensure boolean'ness
680
- deep = !!deep;
681
- // Ensure propertyHandlers are converted for our ease of use
682
- // Transform 1: Ensure array of COPropertyHandlers at the
683
- // cost of potentially having none
684
- propertyHandlers = (Array.isArray(propertyHandlers)
685
- ? propertyHandlers
686
- : [propertyHandlers]).filter(element => element instanceof COPropertyHandler);
687
- // Transform 2: Convert array of handlers into an object keyed
688
- // as { [handler.property]: handler }
689
- const transducer = makeTransducer(propertyHandlers, transduceFromCOHandler);
690
- propertyHandlers = transducer({});
691
- // Rebuild options in the case that we recurse
692
- options = { deep, propertyHandlers };
693
- // Ensure sources have only objects
694
- sources = sources.filter(source => source && typeof source === 'object');
695
- // Ensure the destination is not null
696
- if (!destination) {
697
- destination = {};
698
- }
699
- return [options, destination, sources];
700
- }
701
- export default copyObject;
702
- //# sourceMappingURL=copy.object.js.map