jsql-neo 5.4.2 → 6.0.0-beta2

package/lib/plugins/logger.js

@@ -0,0 +1,35 @@
+/**
+ * logger —— 把数据库操作记录到自定义 logger。
+ *
+ * @example
+ * db.use(require('jsql-neo/lib/plugins').logger({ logger: myLogger, tables: ['users'] }));
+ */
+const { definePlugin } = require('../plugin');
+
+function count(rows) {
+  if (Array.isArray(rows)) return rows.length;
+  return rows === undefined || rows === null ? 0 : 1;
+}
+
+function createLogger(opts = {}) {
+  const logger = typeof opts.logger === 'function' ? opts.logger : (...a) => console.log('[jsql]', ...a);
+  const only = opts.tables ? new Set(opts.tables) : null;
+  const show = t => !only || only.has(t);
+
+  return definePlugin('logger', {
+    config: { tables: opts.tables || null },
+    hooks: {
+      afterInsert(table, rows) { if (show(table)) logger(`insert ${table} +${count(rows)}`); },
+      afterUpdate(table) { if (show(table)) logger(`update ${table}`); },
+      afterDelete(table) { if (show(table)) logger(`delete ${table}`); },
+      afterFind(table) { if (opts.logFinds && show(table)) logger(`find ${table}`); },
+      afterQuery(sql) { if (opts.logQueries) logger(`query ${sql}`); },
+      afterCreateTable(name) { if (show(name)) logger(`createTable ${name}`); },
+      afterDropTable(name) { if (show(name)) logger(`dropTable ${name}`); },
+      onStart() { logger('engine start'); },
+      onStop() { logger('engine stop'); }
+    }
+  });
+}
+
+module.exports = { createLogger, logger: createLogger };

package/lib/plugins/metrics.js

@@ -0,0 +1,38 @@
+/**
+ * metrics —— 统计各类操作的次数，通过 db.plugin('metrics') 读取。
+ *
+ * @example
+ * db.use(require('jsql-neo/lib/plugins').metrics());
+ * db.plugin('metrics').snapshot();   // { insert: 3, update: 1, find: 5, ... }
+ * db.plugin('metrics').reset();
+ */
+const { definePlugin } = require('../plugin');
+
+function createMetrics(opts = {}) {
+  const counters = {};
+
+  const bump = (key, n = 1) => { counters[key] = (counters[key] || 0) + n; };
+  const rowCount = rows => (Array.isArray(rows) ? rows.length : 1);
+
+  return definePlugin('metrics', {
+    api: {
+      snapshot: () => ({ ...counters }),
+      get: key => counters[key] || 0,
+      reset: () => { for (const k of Object.keys(counters)) delete counters[k]; }
+    },
+    hooks: {
+      afterInsert(_t, rows) { bump('insert', rowCount(rows)); bump('insertOps'); },
+      afterUpdate() { bump('update'); },
+      afterDelete() { bump('delete'); },
+      afterFind() { bump('find'); },
+      afterCount() { bump('count'); },
+      afterQuery() { bump('query'); },
+      afterCreateTable() { bump('createTable'); },
+      afterDropTable() { bump('dropTable'); },
+      onStart() { bump('start'); },
+      onStop() { bump('stop'); }
+    }
+  });
+}
+
+module.exports = { createMetrics, metrics: createMetrics };

package/lib/plugins/timestamps.js

@@ -0,0 +1,43 @@
+/**
+ * timestamps —— 自动维护创建/更新时间戳。
+ *
+ * 在插入时补全 createdAt / updatedAt（已存在则不覆盖 createdAt），
+ * 更新时刷新 updatedAt。所有引擎通用，钩子内只原地修改数据、不回调引擎。
+ *
+ * @example
+ * db.use(require('jsql-neo/lib/plugins').timestamps());
+ * db.use(require('jsql-neo/lib/plugins').timestamps({ createdField: 'created_at', updatedField: 'updated_at' }));
+ */
+const { definePlugin } = require('../plugin');
+
+function createTimestamps(opts = {}) {
+  const createdField = opts.createdField || 'createdAt';
+  const updatedField = opts.updatedField || 'updatedAt';
+  const now = typeof opts.now === 'function' ? opts.now : () => new Date().toISOString();
+
+  const stampRow = (row, isInsert) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return;
+    const t = now();
+    if (isInsert && row[createdField] === undefined) row[createdField] = t;
+    if (row[updatedField] === undefined || opts.overwriteUpdated) row[updatedField] = t;
+  };
+
+  return definePlugin('timestamps', {
+    config: { createdField, updatedField },
+    hooks: {
+      beforeInsert(_table, rows) {
+        if (Array.isArray(rows)) rows.forEach(r => stampRow(r, true));
+        else stampRow(rows, true);
+      },
+      // 更新钩子有 [table, id, data] / [table, pairs] / [table, query, updates] 三种形态
+      beforeUpdate(_table, second, third) {
+        if (third !== undefined) { stampRow(third, false); return; }
+        if (Array.isArray(second)) {
+          for (const pair of second) if (Array.isArray(pair)) stampRow(pair[1], false);
+        }
+      }
+    }
+  });
+}
+
+module.exports = { createTimestamps, timestamps: createTimestamps };

package/lib/plugins/validation.js

@@ -0,0 +1,128 @@
+/**
+ * validation —— 基于表 schema 的插入/更新校验，跨引擎行为一致。
+ *
+ * 校验项：not null（插入）、字段类型、maxLength、min/max，以及自定义校验函数。
+ * 违反时抛出 `ER_VALIDATION: table.field ...`。
+ *
+ * @example
+ * db.use(require('jsql-neo/lib/plugins').validation({
+ *   validators: { users: { email: v => /@/.test(v) || 'invalid email' } }
+ * }));
+ */
+const { definePlugin } = require('../plugin');
+
+function normalizeFieldDef(def) {
+  if (typeof def === 'string') {
+    const s = def.toLowerCase();
+    const has = re => new RegExp(re).test(s);
+    const type = s
+      .replace(/\bprimary\s+key\b/g, '')
+      .replace(/\bauto_?increment\b/g, '')
+      .replace(/\bnot\s+null\b/g, '')
+      .replace(/\bunique\b/g, '')
+      .replace(/\bdefault\s+\S+/g, '')
+      .trim();
+    return {
+      type: type || 'string',
+      required: has('\\bnot\\s+null\\b'),
+      primaryKey: has('\\bprimary\\s+key\\b'),
+      autoIncrement: has('\\bauto_?increment\\b'),
+      hasDefault: has('\\bdefault\\s+\\S+')
+    };
+  }
+  if (def && typeof def === 'object') {
+    return {
+      type: String(def.type || 'string').toLowerCase(),
+      required: !!(def.required || def.notNull || def.not_null),
+      nullable: def.nullable,
+      primaryKey: !!(def.primaryKey || def.primary_key),
+      autoIncrement: !!(def.autoIncrement || def.auto_increment),
+      hasDefault: def.default !== undefined,
+      maxLength: def.maxLength !== undefined ? def.maxLength : def.length,
+      min: def.min,
+      max: def.max
+    };
+  }
+  return { type: 'string' };
+}
+
+const TYPE_OF = {
+  string: v => typeof v === 'string',
+  text: v => typeof v === 'string',
+  varchar: v => typeof v === 'string',
+  char: v => typeof v === 'string',
+  integer: v => Number.isInteger(v),
+  int: v => Number.isInteger(v),
+  bigint: v => typeof v === 'bigint' || Number.isInteger(v),
+  float: v => typeof v === 'number' && Number.isFinite(v),
+  double: v => typeof v === 'number' && Number.isFinite(v),
+  number: v => typeof v === 'number' && Number.isFinite(v),
+  numeric: v => typeof v === 'number' && Number.isFinite(v),
+  decimal: v => typeof v === 'number' && Number.isFinite(v),
+  boolean: v => typeof v === 'boolean',
+  bool: v => typeof v === 'boolean',
+  json: v => typeof v === 'object' && v !== null && !Array.isArray(v),
+  object: v => typeof v === 'object' && v !== null && !Array.isArray(v),
+  array: v => Array.isArray(v),
+  date: v => typeof v === 'string' || v instanceof Date,
+  datetime: v => typeof v === 'string' || v instanceof Date,
+  timestamp: v => typeof v === 'string' || v instanceof Date
+};
+
+function checkValue(table, field, def, value, row, custom) {
+  const isNull = value === undefined || value === null;
+  const fail = msg => { throw new Error(`ER_VALIDATION: ${table}.${field} ${msg}`); };
+
+  if (isNull) {
+    if (def.required && !def.hasDefault && def.nullable !== true) fail('is required');
+    return;
+  }
+  const type = def.type;
+  const checker = TYPE_OF[type];
+  if (checker && !checker(value)) fail(`expected ${type}, got ${typeof value}`);
+  if (def.maxLength !== undefined && typeof value === 'string' && value.length > def.maxLength) {
+    fail(`length > ${def.maxLength}`);
+  }
+  if (def.min !== undefined && typeof value === 'number' && value < def.min) fail(`< ${def.min}`);
+  if (def.max !== undefined && typeof value === 'number' && value > def.max) fail(`> ${def.max}`);
+  if (typeof custom === 'function') {
+    const r = custom(value, row);
+    if (r === false) fail('custom validator failed');
+    if (typeof r === 'string') fail(r);
+  }
+}
+
+function createValidation(opts = {}) {
+  const validators = opts.validators || {};
+  // install 时拿到插件上下文（schema 查询），供各钩子闭包使用
+  let engineCtx = null;
+
+  const validateRow = (table, row, partial) => {
+    const schema = engineCtx && engineCtx.getTableSchema(table);
+    if (!schema) return;
+    const tableValidators = validators[table] || {};
+    for (const [field, rawDef] of Object.entries(schema)) {
+      const def = normalizeFieldDef(rawDef);
+      if (partial && !(field in row)) continue;
+      checkValue(table, field, def, row[field], row, tableValidators[field] || validators[field]);
+    }
+  };
+
+  const validateMany = (table, rows, partial) => {
+    if (Array.isArray(rows)) rows.forEach(r => validateRow(table, r, partial));
+    else if (rows && typeof rows === 'object') validateRow(table, rows, partial);
+  };
+
+  return definePlugin('validation', {
+    install(engine, ctx) { engineCtx = ctx; },
+    hooks: {
+      beforeInsert(table, rows) { validateMany(table, rows, false); },
+      beforeUpdate(table, second, third) {
+        if (third !== undefined) { validateMany(table, third, true); return; }
+        if (Array.isArray(second)) for (const p of second) if (Array.isArray(p)) validateMany(table, p[1], true);
+      }
+    }
+  });
+}
+
+module.exports = { createValidation, validation: createValidation };