@nuxodin/item 0.6.18 → 0.6.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxodin/item",
-  "version": "0.6.18",
+  "version": "0.6.20",
   "description": "Reactive state library",
   "type": "module",
   "license": "MIT",

package/src/AsyncDataPoint.js

@@ -5,13 +5,14 @@
         set: value => fetch('https://example.com/todos/1', {method: 'PUT', body: JSON.stringify(value)}).then(res => res.json())
     });
     datapoint.set({title: 'foo', completed: true}); // Returns promise - or undefined if value is already the same - do not rely on return value
+    // a write overtaken by a newer one settles as that one does: "this value or a newer one is saved"
     datapoint.get().then(value => console.log(value));
 
     // API
     datapoint.onchange = ({value}) => console.log('value changed', value);
-    datapoint.ttl = 1000; // cache for 1 second
-    datapoint.optimistic = true; // trust sending value: until the sending is done, the value is the new value, despite the uncertainty that the server will fail
-    datapoint.debounceMs = 5; // debounce period for setter in ms, default 5
+    // options, passed to the constructor (or changed in datapoint.options):
+    //   ttl: 5000 (cache in ms), debounceMs: 5 (setter delay), getRetry / setRetry, getRetryDelay / setRetryDelay,
+    //   optimistic: true (until the sending is done, the value is the new one, though the server may fail)
     datapoint.setLocal({title: 'foo', completed: true}); // set value without saving it to the master (the value comes from the master through an other channel / trusted source)
     */
 
@@ -21,6 +22,7 @@
         createSetter;
         #expectedValue = null; // value while saving
         #setter = null; // current setter promise
+        #writing = Promise.resolve(); // the write running, the next one starts after it
         #getter = null; // current/cached getter promise
         #getterExpiry = Infinity; // ttl is checked lazily on access — no timer per cache entry
         // expired getters count as gone (lazy ttl)
@@ -62,11 +64,15 @@
         #createSetter(value) {
             const {setRetry, setRetryDelay, debounceMs} = this.options;        
             const promise = abortablePromise((resolve, reject) => {
-                retryAsync(
-                    () => this.createSetter(value, promise.controller.signal),
+                const {signal} = promise.controller;
+                // one write at a time: a slow one landing last would leave the remote with an old value
+                const run = this.#writing.then(() => signal.aborted || retryAsync(
+                    () => this.createSetter(value, signal),
                     setRetry,
                     setRetryDelay
-                ).then(resolve, reject);
+                ));
+                this.#writing = run.catch(() => {});
+                run.then(resolve, reject);
             }, debounceMs);
             
             makePromiseTransparent(promise);
@@ -83,18 +89,12 @@
             promise.then(
                 value => {
                     if (this.#getter !== promise) return;
-                    if (!isEqual(oldValue, value)) {
-                        try {
-                            this.onchange?.({value, oldValue});
-                        } catch (err) {
-                            console.error('[item.js] AsyncDataPoint onchange error:', err);
-                        }
-                    }
+                    if (!isEqual(oldValue, value)) this.#notify({value, oldValue});
                 },
                 error => {
                     if (this.#getter !== promise) return;
                     if (error?.name === 'AbortError') return;
-                    this.onchange?.({error, oldValue});
+                    this.#notify({error, oldValue});
                 }
             );
 
@@ -103,6 +103,11 @@
             this.#getterExpiry = duration > 0 ? Date.now() + duration : Infinity;
         }
 
+        #notify(event) {
+            try { this.onchange?.(event); }
+            catch (err) { console.error('[item.js] AsyncDataPoint onchange error:', err); }
+        }
+
         setLocal(value) { this.#cacheGetter(transparentPromiseResolve(value)); }
         setFromPromise(promise) { this.#cacheGetter(makePromiseTransparent(promise)); }
         get isPending() { return this.#cachedGetter?.state === 'pending' || this.#setter?.state === 'pending'; }
@@ -124,18 +129,18 @@
         }
 
         set(value) {
+            const previous = this.#setter, writing = previous?.state === 'pending';
             // Already setting this value
-            if (this.#setter?.state === 'pending' && isEqual(this.#expectedValue, value)) return this.#setter;
-
-            this.#setter?.controller.abort(); // abort previous setter
+            if (writing && isEqual(this.#expectedValue, value)) return previous;
 
-            // ignore if latest getter value is the same
             // Value already set (no-op). Returns undefined to avoid falsy issues (value could be 0, false, etc.)
+            // While a write runs the loaded value is outdated: setting it back is a change.
             const cached = this.#cachedGetter;
-            if (cached?.state === 'fulfilled' && isEqual(cached.value, value)) return;
+            if (!writing && cached?.state === 'fulfilled' && isEqual(cached.value, value)) return;
             
             this.#expectedValue = value;
             const promise = this.#createSetter(value);
+            previous?.controller.abort(promise); // the previous one settles as this one does
             
             this.onpending?.();
 
@@ -146,13 +151,12 @@
                     this.#setter = null;
                     this.#expectedValue = null;
                 },
-                error => {
+                error => { // the failed setter stays: lastError reports it until the next write
                     if (this.#setter !== promise) return;
                     if (error?.name === 'AbortError') return;
                     this.#getter = null;
-                    this.#setter = null;
                     this.#expectedValue = null;
-                    this.onchange?.({ error }); }
+                    this.#notify({ error }); }
             );
 
             return this.#setter = promise;
@@ -223,18 +227,21 @@
     }
 
     /**
-     * Returns a delayed Promise that can be aborted within the specified time (ms).
-     * @param {Promise<any>} fn - A function that returns a Promise.
-     * @param {Number} [ms=1] - The time in milliseconds to delay before resolving the Promise.
+     * Returns a delayed Promise that can be aborted. Aborted with a promise as reason, it settles as
+     * that one does (a newer write taking over), else it rejects with the AbortError.
+     * @param {Function} fn - Called with (resolve, reject) after the delay.
+     * @param {Number} [ms=1] - The time in milliseconds to delay before calling fn.
      * @returns {Promise<any>} - A delayed Promise that can be aborted.
      */
     function abortablePromise(fn, ms=1) { // delayed and therfore abortable within ms
         const controller = new AbortController();
+        const {signal} = controller;
         const promise = new Promise((resolve, reject) => {
-            setTimeout(() => {
-                if (controller.signal.aborted) return reject(new DOMException('aborted', 'AbortError'));
-                fn(resolve, reject);
-            }, ms);
+            const settle = (ok) => (v) => {
+                if (!signal.aborted) return ok(v);
+                signal.reason?.then ? resolve(signal.reason) : reject(signal.reason);
+            };
+            setTimeout(() => signal.aborted ? settle()() : fn(settle(resolve), settle(reject)), ms);
         });
         promise.controller = controller;
         return promise;

package/tools/schema/db/mysql/to-db.js

@@ -40,10 +40,7 @@ function secondaryIndexKind(prop) {
 
 function usableIndexKind(table, name, prop) {
   const kind = secondaryIndexKind(prop);
-  const issue = kind && indexIssue(table, name, prop, kind);
-  if (!issue) return kind;
-  console.warn(issue);
-  return null;
+  return kind && !indexIssue(table, name, prop, kind) ? kind : null;
 }
 
 function indexIssue(table, name, prop, kind) {
@@ -109,6 +106,7 @@ export async function schemaToDb(
   }
 
   const stmts = [];
+  const warnings = [];
   const nextTables = Object.keys(schema.properties ?? {});
   const currTables = Object.keys(current.properties ?? {});
 
@@ -117,6 +115,11 @@ export async function schemaToDb(
     const { fields, required } = tableData(schema.properties[table]);
     const primaries = primaryFields(fields);
     for (const p of primaries) required.add(p); // primary key columns are always NOT NULL
+    for (const [n, f] of fields) {
+      const kind = secondaryIndexKind(f);
+      const issue = kind && indexIssue(table, n, f, kind);
+      if (issue) warnings.push(issue); // the index is left out
+    }
 
     if (!currTables.includes(table)) {
       const cols = fields.map(([n, f]) =>
@@ -196,11 +199,8 @@ export async function schemaToDb(
     }
   }
 
-  for (const stmt of stmts) {
-    console.log(stmt);
-    await query(stmt);
-  }
-  return { diffs, executed: stmts };
+  for (const stmt of stmts) await query(stmt);
+  return { diffs, executed: stmts, warnings };
 }
 
 async function indexStatements(query, table, nextFields, currFields, { patch = false } = {}) {

package/tools/schema/db/pg/to-db.js

@@ -32,13 +32,11 @@ function preserveDefault(prop, currProp) {
         : { ...prop, default: currProp.default }
 }
 
-function secondaryIndexKind(table, name, prop) {
+function secondaryIndexKind(prop) {
     // hnsw needs a fixed length and an operator class; the application builds vector indexes
     if (prop['x-vector']) return null
     if (prop['x-index'] === 'unique') return 'UNIQUE INDEX'
     if (prop['x-index'] === true) return 'INDEX'
-    if (prop['x-index'] === 'fulltext')
-        console.warn(`Skip FULLTEXT INDEX ${table}.${name}: PostgreSQL fulltext requires an expression index`)
     return null
 }
 
@@ -114,6 +112,7 @@ export async function schemaToDb(schema, query, { force = false, patch = false }
     }
 
     const stmts = []
+    const warnings = []
     const nextTables = Object.keys(schema.properties ?? {})
     const currTables = Object.keys(current.properties ?? {})
 
@@ -122,6 +121,10 @@ export async function schemaToDb(schema, query, { force = false, patch = false }
         const { fields, required } = tableData(schema.properties[table])
         const primaries = primaryFields(fields)
         for (const p of primaries) required.add(p)
+        for (const [n, f] of fields) {
+            if (f['x-index'] === 'fulltext' && !f['x-vector'])
+                warnings.push(`Skip FULLTEXT INDEX ${table}.${n}: PostgreSQL fulltext requires an expression index`)
+        }
 
         if (!currTables.includes(table)) {
             const cols = fields.map(([n, f]) =>
@@ -135,7 +138,7 @@ export async function schemaToDb(schema, query, { force = false, patch = false }
             for (const [n, f] of fields) if (f['$comment']) stmts.push(commentStmt(table, n, f['$comment']))
             for (const [n, f] of fields) {
                 if (primarySet.has(n)) continue
-                const kind = secondaryIndexKind(table, n, f)
+                const kind = secondaryIndexKind(f)
                 if (kind) stmts.push(createIndex(table, n, kind))
             }
         } else {
@@ -177,11 +180,8 @@ export async function schemaToDb(schema, query, { force = false, patch = false }
     const vectors = nextTables.some(t => tableData(schema.properties[t]).fields.some(([, f]) => f['x-vector']))
     if (vectors && stmts.length) stmts.unshift('CREATE EXTENSION IF NOT EXISTS vector;')
 
-    for (const stmt of stmts) {
-        console.log(stmt)
-        await query(stmt)
-    }
-    return { diffs, executed: stmts }
+    for (const stmt of stmts) await query(stmt)
+    return { diffs, executed: stmts, warnings }
 }
 
 async function indexStatements(query, table, nextFields, currFields, { patch = false } = {}) {
@@ -198,7 +198,7 @@ async function indexStatements(query, table, nextFields, currFields, { patch = f
 
     for (const [name, prop] of nextFields) {
         if (nextPrimary.has(name)) continue
-        const nextKind = secondaryIndexKind(table, name, prop)
+        const nextKind = secondaryIndexKind(prop)
         const curr = indexes.secondary.find(i => i.column === name)
         const currKind = curr ? curr.unique ? 'UNIQUE INDEX' : 'INDEX' : null
         const changed = curr && currKind !== nextKind
@@ -209,7 +209,7 @@ async function indexStatements(query, table, nextFields, currFields, { patch = f
 
     if (!patch) {
         for (const curr of indexes.secondary) {
-            const wanted = nextFields.find(([name, prop]) => name === curr.column && secondaryIndexKind(table, name, prop))
+            const wanted = nextFields.find(([name, prop]) => name === curr.column && secondaryIndexKind(prop))
             if (!wanted) before.push(`DROP INDEX ${quoteId(curr.key)};`)
         }
     }

package/tools/schema/db/sqlite/to-db.js

@@ -34,8 +34,6 @@ function createBody(table, fields, primaries) {
     const solo = soloIntPrimary(fields, primaries)
     const cols = fields.map(([n, f]) => {
         const isPk = n === solo
-        if (f['x-autoincrement'] && !isPk)
-            console.warn(`Skip AUTOINCREMENT ${table}.${n}: SQLite auto-increments only a sole INTEGER PRIMARY KEY — nothing fills this column`)
         // Only `INTEGER PRIMARY KEY` is the rowid alias, and AUTOINCREMENT is legal nowhere else —
         // so a boolean key keeps the integer spelling, which SQLite would otherwise reject.
         let def = toFieldDef(n, isPk ? { ...f, type: 'integer' } : f)
@@ -50,11 +48,17 @@ function indexKind(table, name, prop) {
     if (prop['x-vector']) return null // sqlite-vec scans; a B-tree over vectors helps nothing
     if (prop['x-index'] === 'unique') return 'UNIQUE INDEX'
     if (prop['x-index'] === true) return 'INDEX'
-    if (prop['x-index'] === 'fulltext')
-        console.warn(`Skip FULLTEXT INDEX ${table}.${name}: SQLite fulltext requires a virtual FTS table`)
     return null
 }
 
+/** What the schema asks of a field that SQLite cannot do; the field is created without it. */
+function fieldWarning(table, name, prop, solo) {
+    if (prop['x-autoincrement'] && name !== solo)
+        return `Skip AUTOINCREMENT ${table}.${name}: SQLite auto-increments only a sole INTEGER PRIMARY KEY — nothing fills this column`
+    if (prop['x-index'] === 'fulltext' && !prop['x-vector'])
+        return `Skip FULLTEXT INDEX ${table}.${name}: SQLite fulltext requires a virtual FTS table`
+}
+
 function createIndex(table, name, kind) {
     return `CREATE ${kind} ${quoteId(indexName(table, name))} ON ${quoteId(table)} (${quoteId(name)});`
 }
@@ -94,12 +98,18 @@ export async function schemaToDb(schema, query, { force = false, patch = false }
     }
 
     const stmts      = []
+    const warnings   = []
     const nextTables = Object.keys(schema.properties ?? {})
     const currTables = Object.keys(current.properties ?? {})
 
     for (const table of nextTables) {
         const fields    = tableFields(schema.properties[table])
         const primaries = fields.filter(([, f]) => f['x-index'] === 'primary').map(([n]) => n)
+        const solo      = soloIntPrimary(fields, primaries)
+        for (const [n, f] of fields) {
+            const warning = fieldWarning(table, n, f, solo)
+            if (warning) warnings.push(warning)
+        }
 
         if (!currTables.includes(table)) {
             // Idea: WITHOUT ROWID when the primary key is not a single integer column and all other columns
@@ -144,9 +154,6 @@ export async function schemaToDb(schema, query, { force = false, patch = false }
         }
     }
 
-    for (const stmt of stmts) {
-        console.log(stmt)
-        await query(stmt)
-    }
-    return { diffs, executed: stmts }
+    for (const stmt of stmts) await query(stmt)
+    return { diffs, executed: stmts, warnings }
 }