@functional-systems/memdrive 0.0.0-stage → 0.1.0-dev.8

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 (97) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/LICENSE +201 -0
  3. package/README.md +232 -2
  4. package/dist/commonjs/chunking.d.ts +7 -0
  5. package/dist/commonjs/chunking.d.ts.map +1 -0
  6. package/dist/commonjs/chunking.js +46 -0
  7. package/dist/commonjs/chunking.js.map +1 -0
  8. package/dist/commonjs/errors.d.ts +17 -0
  9. package/dist/commonjs/errors.d.ts.map +1 -0
  10. package/dist/commonjs/errors.js +44 -0
  11. package/dist/commonjs/errors.js.map +1 -0
  12. package/dist/commonjs/filter.d.ts +30 -0
  13. package/dist/commonjs/filter.d.ts.map +1 -0
  14. package/dist/commonjs/filter.js +224 -0
  15. package/dist/commonjs/filter.js.map +1 -0
  16. package/dist/commonjs/index.d.ts +8 -0
  17. package/dist/commonjs/index.d.ts.map +1 -0
  18. package/dist/commonjs/index.js +343 -0
  19. package/dist/commonjs/index.js.map +1 -0
  20. package/dist/commonjs/package.json +3 -0
  21. package/dist/commonjs/storage.d.ts +274 -0
  22. package/dist/commonjs/storage.d.ts.map +1 -0
  23. package/dist/commonjs/storage.js +861 -0
  24. package/dist/commonjs/storage.js.map +1 -0
  25. package/dist/commonjs/tools/definitions.d.ts +5 -0
  26. package/dist/commonjs/tools/definitions.d.ts.map +1 -0
  27. package/dist/commonjs/tools/definitions.js +129 -0
  28. package/dist/commonjs/tools/definitions.js.map +1 -0
  29. package/dist/commonjs/tools/index.d.ts +6 -0
  30. package/dist/commonjs/tools/index.d.ts.map +1 -0
  31. package/dist/commonjs/tools/index.js +104 -0
  32. package/dist/commonjs/tools/index.js.map +1 -0
  33. package/dist/commonjs/tools/types.d.ts +50 -0
  34. package/dist/commonjs/tools/types.d.ts.map +1 -0
  35. package/dist/commonjs/tools/types.js +3 -0
  36. package/dist/commonjs/tools/types.js.map +1 -0
  37. package/dist/commonjs/types.d.ts +277 -0
  38. package/dist/commonjs/types.d.ts.map +1 -0
  39. package/dist/commonjs/types.js +3 -0
  40. package/dist/commonjs/types.js.map +1 -0
  41. package/dist/commonjs/values.d.ts +17 -0
  42. package/dist/commonjs/values.d.ts.map +1 -0
  43. package/dist/commonjs/values.js +90 -0
  44. package/dist/commonjs/values.js.map +1 -0
  45. package/dist/esm/chunking.d.ts +7 -0
  46. package/dist/esm/chunking.d.ts.map +1 -0
  47. package/dist/esm/chunking.js +42 -0
  48. package/dist/esm/chunking.js.map +1 -0
  49. package/dist/esm/errors.d.ts +17 -0
  50. package/dist/esm/errors.d.ts.map +1 -0
  51. package/dist/esm/errors.js +36 -0
  52. package/dist/esm/errors.js.map +1 -0
  53. package/dist/esm/filter.d.ts +30 -0
  54. package/dist/esm/filter.d.ts.map +1 -0
  55. package/dist/esm/filter.js +209 -0
  56. package/dist/esm/filter.js.map +1 -0
  57. package/dist/esm/index.d.ts +8 -0
  58. package/dist/esm/index.d.ts.map +1 -0
  59. package/dist/esm/index.js +335 -0
  60. package/dist/esm/index.js.map +1 -0
  61. package/dist/esm/package.json +3 -0
  62. package/dist/esm/storage.d.ts +274 -0
  63. package/dist/esm/storage.d.ts.map +1 -0
  64. package/dist/esm/storage.js +845 -0
  65. package/dist/esm/storage.js.map +1 -0
  66. package/dist/esm/tools/definitions.d.ts +5 -0
  67. package/dist/esm/tools/definitions.d.ts.map +1 -0
  68. package/dist/esm/tools/definitions.js +126 -0
  69. package/dist/esm/tools/definitions.js.map +1 -0
  70. package/dist/esm/tools/index.d.ts +6 -0
  71. package/dist/esm/tools/index.d.ts.map +1 -0
  72. package/dist/esm/tools/index.js +101 -0
  73. package/dist/esm/tools/index.js.map +1 -0
  74. package/dist/esm/tools/types.d.ts +50 -0
  75. package/dist/esm/tools/types.d.ts.map +1 -0
  76. package/dist/esm/tools/types.js +2 -0
  77. package/dist/esm/tools/types.js.map +1 -0
  78. package/dist/esm/types.d.ts +277 -0
  79. package/dist/esm/types.d.ts.map +1 -0
  80. package/dist/esm/types.js +2 -0
  81. package/dist/esm/types.js.map +1 -0
  82. package/dist/esm/values.d.ts +17 -0
  83. package/dist/esm/values.d.ts.map +1 -0
  84. package/dist/esm/values.js +87 -0
  85. package/dist/esm/values.js.map +1 -0
  86. package/docs/tools.md +163 -0
  87. package/package.json +99 -4
  88. package/src/chunking.ts +32 -0
  89. package/src/errors.ts +40 -0
  90. package/src/filter.ts +189 -0
  91. package/src/index.ts +323 -0
  92. package/src/storage.ts +765 -0
  93. package/src/tools/definitions.ts +156 -0
  94. package/src/tools/index.ts +97 -0
  95. package/src/tools/types.ts +45 -0
  96. package/src/types.ts +273 -0
  97. package/src/values.ts +103 -0
package/src/values.ts ADDED
@@ -0,0 +1,103 @@
1
+ import { MemDriveError, requireInput, checkAbort } from './errors.js';
2
+ import { buildFilter, fieldType } from './filter.js';
3
+ import type { CountValuesResult, MetadataSchema, RequestOptions } from './types.js';
4
+
5
+ type NativeObject = Record<string, unknown>;
6
+ export type ValueSchedule = <T>(operation: (options?: RequestOptions) => Promise<T>) => Promise<T>;
7
+ interface CounterOptions {
8
+ describe: (options?: RequestOptions) => Promise<unknown>;
9
+ query: (body: NativeObject, options?: RequestOptions) => Promise<unknown>;
10
+ metadataSchema: () => MetadataSchema;
11
+ schemaTtlMs?: number;
12
+ valuesTtlMs?: number;
13
+ now?: () => number;
14
+ }
15
+ interface CacheEntry {
16
+ expires: number | null;
17
+ signal: AbortSignal | undefined;
18
+ promise: Promise<unknown>;
19
+ }
20
+ interface FacetBucket { value: string; count: number }
21
+ const array = (value: unknown): value is unknown[] => Array.isArray(value);
22
+ const object = (value: unknown): value is NativeObject => value !== null && typeof value === 'object' && !Array.isArray(value);
23
+
24
+ // Each counter is bound to one collection/branch. Writes through any view of the
25
+ // same backend invalidate its cache; outside writes become visible after the TTL.
26
+ export function createValueCounter({ describe, query, metadataSchema,
27
+ schemaTtlMs = 300000, valuesTtlMs = 60000, now = Date.now }: CounterOptions) {
28
+ const cache = new Map<string, CacheEntry>();
29
+ const cached = async <T>(key: string, ttl: number, load: () => Promise<T>, signal?: AbortSignal): Promise<T> => {
30
+ checkAbort(signal);
31
+ for (const [oldKey, entry] of cache)
32
+ if (entry.expires !== null && entry.expires <= now()) cache.delete(oldKey);
33
+ let entry = cache.get(key);
34
+ // Different cancellation scopes cannot share an in-flight request.
35
+ if (!entry || (entry.expires === null && entry.signal !== signal)) {
36
+ const loading: CacheEntry = { expires: null, signal, promise: Promise.resolve().then(load).then(value => {
37
+ loading.expires = now() + ttl;
38
+ loading.signal = undefined;
39
+ return value;
40
+ }, error => {
41
+ if (cache.get(key) === loading) cache.delete(key);
42
+ throw error;
43
+ }) };
44
+ entry = loading;
45
+ cache.set(key, loading);
46
+ }
47
+ const value = await entry.promise;
48
+ checkAbort(signal);
49
+ // Private key namespaces bind entries to the same loader result type.
50
+ return structuredClone(value) as T;
51
+ };
52
+ return {
53
+ invalidate() { cache.clear(); },
54
+ async countValues(input: unknown, schedule?: ValueSchedule, signal?: AbortSignal): Promise<CountValuesResult> {
55
+ checkAbort(signal);
56
+ let args: unknown;
57
+ try { args = structuredClone(input); }
58
+ catch (cause) { throw new MemDriveError('INVALID_INPUT', 'Value count input must be cloneable data.', { cause }); }
59
+ requireInput(object(args) && Object.keys(args).every(key => ['fields', 'filter', 'excludeIds', 'limit'].includes(key)),
60
+ 'Use fields, filter, excludeIds and limit for value counts.');
61
+ const { fields, filter, excludeIds = [], limit = 10 } = args;
62
+ requireInput(array(fields) && fields.length > 0 && fields.length <= 5
63
+ && fields.every((field): field is string => typeof field === 'string' && field.length > 0)
64
+ && new Set(fields).size === fields.length, 'fields must contain 1 to 5 distinct keyword field names (the native facet limit).');
65
+ requireInput(array(excludeIds) && excludeIds.every((id): id is string => typeof id === 'string' && id.trim().length > 0)
66
+ && new Set(excludeIds).size === excludeIds.length, 'excludeIds must contain distinct canonical IDs.');
67
+ requireInput(typeof limit === 'number' && Number.isSafeInteger(limit) && limit >= 1 && limit <= 100,
68
+ 'limit must be an integer from 1 to 100.');
69
+ const execute: ValueSchedule = schedule ?? (operation => operation({ signal }));
70
+ const schema = await cached('schema', schemaTtlMs, async () => {
71
+ // The backend refresh validates the complete collection configuration.
72
+ await execute(describe);
73
+ return metadataSchema();
74
+ }, signal);
75
+ requireInput(fields.every(field => ['string', 'string[]'].includes(fieldType(field, schema) ?? '')),
76
+ 'countValues supports id and declared string or string[] metadata fields.');
77
+ const population = { bool: [
78
+ { ...buildFilter([filter], excludeIds, schema), occur: 'filter' },
79
+ { queryString: { query: '"mem"', defaultField: 'kind' }, occur: 'filter' },
80
+ ] };
81
+ const sorted = [...fields].sort();
82
+ const size = limit < 100 ? limit + 1 : limit;
83
+ const key = JSON.stringify(['counts', population, sorted, limit, schema]);
84
+ return cached(key, valuesTtlMs, async () => {
85
+ const response = await execute(options => query({ size: 0, query: population,
86
+ facets: Object.fromEntries(sorted.map(field => [field === 'id' ? 'memId' : field, { size }])) }, options));
87
+ const facets = object(response) && object(response.facets) ? response.facets : undefined;
88
+ const values = Object.fromEntries(sorted.map(field => {
89
+ const facet = facets?.[field === 'id' ? 'memId' : field];
90
+ const buckets = object(facet) ? facet.buckets : undefined;
91
+ if (!array(buckets) || buckets.length > size
92
+ || !buckets.every((bucket): bucket is FacetBucket => object(bucket) && typeof bucket.value === 'string'
93
+ && typeof bucket.count === 'number' && Number.isSafeInteger(bucket.count) && bucket.count >= 0)
94
+ || new Set(buckets.map(bucket => bucket.value)).size !== buckets.length)
95
+ throw new MemDriveError('INVALID_RESPONSE', 'Value counts returned invalid facet buckets.');
96
+ return [field, { buckets: buckets.slice(0, limit),
97
+ hasMore: buckets.length > limit ? true : buckets.length < 100 ? false : null }];
98
+ }));
99
+ return { values, asOf: new Date(now()).toISOString() };
100
+ }, signal);
101
+ },
102
+ };
103
+ }