@yunsoft/yuncms-core 0.1.0

package/src/migrations.js

@@ -0,0 +1,81 @@
+const JOURNAL_TABLE = 'yuncms_schema_migrations';
+
+export async function ensureMigrationJournal(database) {
+  await database.query(`
+    CREATE TABLE IF NOT EXISTS ${JOURNAL_TABLE} (
+      id VARCHAR(191) NOT NULL PRIMARY KEY,
+      applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+}
+
+export async function readAppliedMigrations(database) {
+  const [rows] = await database.query(`SELECT id FROM ${JOURNAL_TABLE} ORDER BY id ASC`);
+  return new Set(rows.map((row) => row.id));
+}
+
+export function validateMigration(migration) {
+  if (!migration || typeof migration !== 'object') throw new Error('Migration must be an object');
+  if (!migration.id || typeof migration.id !== 'string') throw new Error('Migration id is required');
+  if (!Array.isArray(migration.statements) || migration.statements.length === 0) {
+    throw new Error(`Migration ${migration.id} must contain statements`);
+  }
+  if (migration.statements.some((statement) => typeof statement !== 'string' || !statement.trim())) {
+    throw new Error(`Migration ${migration.id} contains an invalid statement`);
+  }
+  return migration;
+}
+
+export async function applyMigrations(database, migrations) {
+  if (!database) throw new Error('Database handle is required');
+  if (!Array.isArray(migrations)) throw new Error('Migrations must be an array');
+
+  await ensureMigrationJournal(database);
+  const applied = await readAppliedMigrations(database);
+  const newlyApplied = [];
+
+  for (const rawMigration of migrations) {
+    const migration = validateMigration(rawMigration);
+    if (applied.has(migration.id)) continue;
+
+    for (const statement of migration.statements) {
+      await database.query(statement);
+    }
+
+    await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
+    applied.add(migration.id);
+    newlyApplied.push(migration.id);
+  }
+
+  return {
+    applied: [...applied].sort(),
+    newlyApplied,
+  };
+}
+
+export async function assertMigrationsApplied(database, requiredMigrationIds) {
+  let applied;
+
+  try {
+    applied = await readAppliedMigrations(database);
+  } catch (error) {
+    if (error?.code === 'ER_NO_SUCH_TABLE') {
+      const migrationError = new Error('Database bootstrap is required');
+      migrationError.code = 'DATABASE_MIGRATION_REQUIRED';
+      migrationError.missingMigrations = [...requiredMigrationIds];
+      throw migrationError;
+    }
+    throw error;
+  }
+
+  const missing = requiredMigrationIds.filter((id) => !applied.has(id));
+
+  if (missing.length > 0) {
+    const error = new Error(`Database bootstrap is incomplete. Missing migrations: ${missing.join(', ')}`);
+    error.code = 'DATABASE_MIGRATION_REQUIRED';
+    error.missingMigrations = missing;
+    throw error;
+  }
+
+  return true;
+}

package/src/permission-validation.js

@@ -0,0 +1,63 @@
+import { compileFilter } from './query.js';
+
+function validationError(message, path = null) {
+  const error = new Error(message);
+  error.code = 'VALIDATION_FAILED';
+  if (path) error.path = path;
+  return error;
+}
+
+function compare(operator, actual, expected) {
+  switch (operator) {
+    case '_eq': return actual === expected;
+    case '_neq': return actual !== expected;
+    case '_lt': return actual != null && actual < expected;
+    case '_lte': return actual != null && actual <= expected;
+    case '_gt': return actual != null && actual > expected;
+    case '_gte': return actual != null && actual >= expected;
+    case '_in': return expected.some((candidate) => actual === candidate);
+    case '_nin': return !expected.some((candidate) => actual === candidate);
+    case '_null': return expected ? actual == null : actual != null;
+    case '_nnull': return expected ? actual != null : actual == null;
+    case '_contains': return actual != null && String(actual).includes(String(expected));
+    case '_starts_with': return actual != null && String(actual).startsWith(String(expected));
+    case '_ends_with': return actual != null && String(actual).endsWith(String(expected));
+    default: return false;
+  }
+}
+
+function evaluateNode(record, node) {
+  for (const [key, value] of Object.entries(node)) {
+    if (key === '_and') {
+      if (!value.every((child) => evaluateNode(record, child))) return false;
+      continue;
+    }
+    if (key === '_or') {
+      if (!value.some((child) => evaluateNode(record, child))) return false;
+      continue;
+    }
+
+    const actual = record[key];
+    for (const [operator, expected] of Object.entries(value)) {
+      if (!compare(operator, actual, expected)) return false;
+    }
+  }
+  return true;
+}
+
+export function assertPermissionValidationRule(rule, schema) {
+  if (rule == null) return null;
+  compileFilter(rule, schema);
+  return rule;
+}
+
+export function evaluatePermissionValidation(record, rule, schema) {
+  if (rule == null) return true;
+  assertPermissionValidationRule(rule, schema);
+  return evaluateNode(record, rule);
+}
+
+export function enforcePermissionValidation(record, rule, schema, { path = 'validation' } = {}) {
+  if (evaluatePermissionValidation(record, rule, schema)) return record;
+  throw validationError('Record does not satisfy the permission validation rule', path);
+}

package/src/query.js

@@ -0,0 +1,193 @@
+import { quoteIdentifier } from './identifier.js';
+
+const QUERY_KEYS = new Set(['fields', 'filter', 'sort', 'limit', 'offset']);
+const FILTER_OPERATORS = new Set([
+  '_eq', '_neq', '_lt', '_lte', '_gt', '_gte',
+  '_in', '_nin', '_null', '_nnull',
+  '_contains', '_starts_with', '_ends_with',
+]);
+
+function queryError(message, path = null) {
+  const error = new Error(message);
+  error.code = 'INVALID_QUERY';
+  if (path) error.path = path;
+  return error;
+}
+
+function normalizeDelimited(value, label) {
+  if (value == null || value === '') return null;
+  const values = Array.isArray(value) ? value : String(value).split(',');
+  const normalized = values.map((item) => String(item).trim()).filter(Boolean);
+  if (normalized.length === 0) throw queryError(`${label} cannot be empty`, label);
+  return normalized;
+}
+
+function normalizeInteger(value, fallback, { label, min, max }) {
+  if (value == null || value === '') return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) {
+    throw queryError(`${label} must be an integer between ${min} and ${max}`, label);
+  }
+  return number;
+}
+
+function normalizeFilter(value) {
+  if (value == null || value === '') return null;
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('not an object');
+      }
+      return parsed;
+    } catch {
+      throw queryError('filter must be a valid JSON object', 'filter');
+    }
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw queryError('filter must be an object', 'filter');
+  }
+  return value;
+}
+
+export function parseItemsQuery(raw = {}, { defaultLimit = 100, maxLimit = 500 } = {}) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw queryError('Query must be an object');
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (!QUERY_KEYS.has(key)) throw queryError(`Unknown query parameter: ${key}`, key);
+  }
+
+  return {
+    fields: normalizeDelimited(raw.fields, 'fields'),
+    filter: normalizeFilter(raw.filter),
+    sort: normalizeDelimited(raw.sort, 'sort'),
+    limit: normalizeInteger(raw.limit, defaultLimit, { label: 'limit', min: 1, max: maxLimit }),
+    offset: normalizeInteger(raw.offset, 0, { label: 'offset', min: 0, max: Number.MAX_SAFE_INTEGER }),
+  };
+}
+
+function resolveField(schema, field, path = field) {
+  if (!schema?.fields?.[field]) throw queryError(`Unknown field: ${field}`, path);
+  return schema.fields[field];
+}
+
+export function compileSelectFields(fields, schema) {
+  const selected = !fields || fields.includes('*') ? Object.keys(schema.fields) : fields;
+  if (selected.length === 0) throw queryError('At least one field must be selected', 'fields');
+
+  const unique = [...new Set(selected)];
+  return {
+    fields: unique,
+    sql: unique.map((field) => {
+      resolveField(schema, field, `fields.${field}`);
+      return quoteIdentifier(field, 'field name');
+    }).join(', '),
+  };
+}
+
+export function compileSort(sort, schema) {
+  if (!sort) return '';
+
+  const parts = sort.map((entry, index) => {
+    const descending = entry.startsWith('-');
+    const field = descending ? entry.slice(1) : entry;
+    if (!field) throw queryError('Sort field cannot be empty', `sort.${index}`);
+    resolveField(schema, field, `sort.${index}`);
+    return `${quoteIdentifier(field, 'field name')} ${descending ? 'DESC' : 'ASC'}`;
+  });
+
+  return parts.length ? ` ORDER BY ${parts.join(', ')}` : '';
+}
+
+function escapeLike(value) {
+  return String(value).replace(/[\\%_]/g, '\\$&');
+}
+
+function compileOperator(fieldSql, operator, value, path) {
+  if (!FILTER_OPERATORS.has(operator)) throw queryError(`Unknown filter operator: ${operator}`, path);
+
+  switch (operator) {
+    case '_eq':
+      if (value === null) throw queryError('Use _null for NULL comparisons', path);
+      return { sql: `${fieldSql} = ?`, params: [value] };
+    case '_neq':
+      if (value === null) throw queryError('Use _nnull for NULL comparisons', path);
+      return { sql: `${fieldSql} <> ?`, params: [value] };
+    case '_lt': return { sql: `${fieldSql} < ?`, params: [value] };
+    case '_lte': return { sql: `${fieldSql} <= ?`, params: [value] };
+    case '_gt': return { sql: `${fieldSql} > ?`, params: [value] };
+    case '_gte': return { sql: `${fieldSql} >= ?`, params: [value] };
+    case '_in':
+    case '_nin': {
+      if (!Array.isArray(value)) throw queryError(`${operator} requires an array`, path);
+      if (value.length === 0) return { sql: operator === '_in' ? '0 = 1' : '1 = 1', params: [] };
+      const placeholders = value.map(() => '?').join(', ');
+      return {
+        sql: `${fieldSql} ${operator === '_in' ? 'IN' : 'NOT IN'} (${placeholders})`,
+        params: value,
+      };
+    }
+    case '_null':
+    case '_nnull': {
+      if (typeof value !== 'boolean') throw queryError(`${operator} requires a boolean`, path);
+      const wantsNull = operator === '_null' ? value : !value;
+      return { sql: `${fieldSql} IS ${wantsNull ? '' : 'NOT '}NULL`, params: [] };
+    }
+    case '_contains':
+      return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`%${escapeLike(value)}%`] };
+    case '_starts_with':
+      return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`${escapeLike(value)}%`] };
+    case '_ends_with':
+      return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`%${escapeLike(value)}`] };
+    default:
+      throw queryError(`Unknown filter operator: ${operator}`, path);
+  }
+}
+
+function compileFilterObject(filter, schema, path = 'filter') {
+  if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+    throw queryError('Filter node must be an object', path);
+  }
+
+  const fragments = [];
+  const params = [];
+
+  for (const [key, value] of Object.entries(filter)) {
+    if (key === '_and' || key === '_or') {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw queryError(`${key} requires a non-empty array`, `${path}.${key}`);
+      }
+      const children = value.map((child, index) =>
+        compileFilterObject(child, schema, `${path}.${key}.${index}`));
+      fragments.push(`(${children.map((child) => child.sql).join(key === '_and' ? ' AND ' : ' OR ')})`);
+      for (const child of children) params.push(...child.params);
+      continue;
+    }
+
+    resolveField(schema, key, `${path}.${key}`);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw queryError('Field filters must be operator objects', `${path}.${key}`);
+    }
+
+    const fieldSql = quoteIdentifier(key, 'field name');
+    const fieldFragments = [];
+    for (const [operator, operatorValue] of Object.entries(value)) {
+      const compiled = compileOperator(fieldSql, operator, operatorValue, `${path}.${key}.${operator}`);
+      fieldFragments.push(compiled.sql);
+      params.push(...compiled.params);
+    }
+    if (fieldFragments.length === 0) throw queryError('Field filter cannot be empty', `${path}.${key}`);
+    fragments.push(`(${fieldFragments.join(' AND ')})`);
+  }
+
+  if (fragments.length === 0) throw queryError('Filter cannot be empty', path);
+  return { sql: fragments.join(' AND '), params };
+}
+
+export function compileFilter(filter, schema) {
+  if (!filter) return { sql: '', params: [] };
+  const compiled = compileFilterObject(filter, schema);
+  return { sql: ` WHERE ${compiled.sql}`, params: compiled.params };
+}

package/src/relation-expansion.js

@@ -0,0 +1,216 @@
+import { assertIdentifier } from './identifier.js';
+import { SchemaCache } from './schema.js';
+import { ItemsService } from './services/items-service.js';
+
+const MAX_EXPAND_FIELDS = 8;
+const defaultSchemaCache = new SchemaCache();
+
+function expansionError(code, message, path = null) {
+  const error = new Error(message);
+  error.code = code;
+  if (path) error.path = path;
+  return error;
+}
+
+function normalizeDelimited(value) {
+  if (value == null || value === '') return [];
+  const values = Array.isArray(value) ? value : String(value).split(',');
+  return values.map((entry) => String(entry).trim()).filter(Boolean);
+}
+
+export function parseExpandInput(value) {
+  const fields = [...new Set(normalizeDelimited(value))];
+  if (fields.length > MAX_EXPAND_FIELDS) {
+    throw expansionError(
+      'INVALID_QUERY',
+      `expand supports at most ${MAX_EXPAND_FIELDS} direct relation fields`,
+      'expand',
+    );
+  }
+
+  for (const field of fields) {
+    try {
+      assertIdentifier(field, 'expand field');
+    } catch {
+      throw expansionError('INVALID_QUERY', `Invalid expand field: ${field}`, 'expand');
+    }
+  }
+  return fields;
+}
+
+function parseRelationMetadata(value) {
+  if (value == null || typeof value === 'object') return value ?? {};
+  try {
+    return JSON.parse(value);
+  } catch {
+    return {};
+  }
+}
+
+function withExpansionFields(rawFields, expandFields) {
+  if (rawFields == null || rawFields === '') return rawFields;
+  const selected = normalizeDelimited(rawFields);
+  if (selected.includes('*')) return selected;
+  return [...new Set([...selected, ...expandFields])];
+}
+
+function withoutExpand(query = {}, expandFields = []) {
+  const base = { ...query };
+  delete base.expand;
+  if (expandFields.length > 0 && Object.hasOwn(base, 'fields')) {
+    base.fields = withExpansionFields(base.fields, expandFields);
+  }
+  return base;
+}
+
+async function schemaSnapshot(options) {
+  if (options.schema) return options.schema;
+  const cache = options.schemaCache ?? defaultSchemaCache;
+  return cache.get(options.database);
+}
+
+function directRelation(snapshot, collection, field) {
+  const relation = snapshot.relationByManyField?.get(`${collection}.${field}`);
+  if (!relation) {
+    throw expansionError(
+      'INVALID_QUERY',
+      `Field is not a direct relation and cannot be expanded: ${collection}.${field}`,
+      `expand.${field}`,
+    );
+  }
+
+  const metadata = parseRelationMetadata(relation.metadata);
+  if (relation.junction_collection || metadata.kind === 'm2m') {
+    throw expansionError(
+      'UNSUPPORTED_RELATION_EXPANSION',
+      `Only direct M2O fields can be expanded in V1: ${collection}.${field}`,
+      `expand.${field}`,
+    );
+  }
+  return relation;
+}
+
+async function validateSourceExpansions({ collection, expandFields, options, service }) {
+  const snapshot = await schemaSnapshot(options);
+  const sourceSchema = snapshot.collections?.[collection];
+  if (!sourceSchema) {
+    throw expansionError('COLLECTION_NOT_FOUND', `Unknown collection: ${collection}`);
+  }
+  if (expandFields.length === 0) return snapshot;
+
+  const permission = await service.resolvePermission('read');
+  for (const field of expandFields) {
+    if (!sourceSchema.fields?.[field] || (permission.fields && !permission.fields.includes(field))) {
+      throw expansionError('INVALID_QUERY', `Unknown field: ${field}`, `expand.${field}`);
+    }
+    directRelation(snapshot, collection, field);
+  }
+  return snapshot;
+}
+
+async function expandRows({ collection, rows, expandFields, options, ItemsServiceClass, snapshot }) {
+  if (expandFields.length === 0 || rows.length === 0) return rows;
+  const effectiveSnapshot = snapshot ?? await schemaSnapshot(options);
+  let expandedRows = rows.map((row) => ({ ...row }));
+
+  for (const field of expandFields) {
+    const relation = directRelation(effectiveSnapshot, collection, field);
+    const targetCollection = relation.one_collection;
+    const targetKey = relation.one_field
+      || effectiveSnapshot.collections?.[targetCollection]?.primary_key
+      || 'id';
+    const values = [...new Set(
+      expandedRows
+        .map((row) => row[field])
+        .filter((value) => value != null && value !== '')
+        .map((value) => String(value)),
+    )];
+
+    if (values.length === 0) {
+      expandedRows = expandedRows.map((row) => ({ ...row, [field]: null }));
+      continue;
+    }
+
+    const targetService = new ItemsServiceClass(targetCollection, options);
+    const targetRows = await targetService.readMany({
+      filter: { [targetKey]: { _in: values } },
+      limit: Math.min(values.length, 500),
+    });
+
+    const byKey = new Map();
+    for (const target of targetRows) {
+      if (!Object.hasOwn(target, targetKey)) {
+        throw expansionError(
+          'FORBIDDEN_FIELD',
+          `Expanded relation key is not readable: ${targetCollection}.${targetKey}`,
+          `expand.${field}`,
+        );
+      }
+      byKey.set(String(target[targetKey]), target);
+    }
+
+    expandedRows = expandedRows.map((row) => ({
+      ...row,
+      [field]: row[field] == null || row[field] === ''
+        ? null
+        : (byKey.get(String(row[field])) ?? null),
+    }));
+  }
+
+  return expandedRows;
+}
+
+export async function readManyWithRelations({
+  collection,
+  query = {},
+  options = {},
+  ItemsServiceClass = ItemsService,
+} = {}) {
+  assertIdentifier(collection, 'collection name');
+  const expandFields = parseExpandInput(query.expand);
+  const service = new ItemsServiceClass(collection, options);
+  const snapshot = await validateSourceExpansions({ collection, expandFields, options, service });
+  const result = await service.readManyWithMeta(withoutExpand(query, expandFields));
+  const data = await expandRows({
+    collection,
+    rows: result.data,
+    expandFields,
+    options,
+    ItemsServiceClass,
+    snapshot,
+  });
+  return { ...result, data };
+}
+
+export async function readOneWithRelations({
+  collection,
+  id,
+  query = {},
+  options = {},
+  ItemsServiceClass = ItemsService,
+} = {}) {
+  assertIdentifier(collection, 'collection name');
+  for (const key of Object.keys(query ?? {})) {
+    if (!['fields', 'expand'].includes(key)) {
+      throw expansionError('INVALID_QUERY', `Unknown query parameter: ${key}`, key);
+    }
+  }
+
+  const expandFields = parseExpandInput(query.expand);
+  const service = new ItemsServiceClass(collection, options);
+  const snapshot = await validateSourceExpansions({ collection, expandFields, options, service });
+  const fields = withExpansionFields(query.fields ?? null, expandFields);
+  const record = await service.readOne(id, { fields });
+  if (!record) return null;
+  const [expanded] = await expandRows({
+    collection,
+    rows: [record],
+    expandFields,
+    options,
+    ItemsServiceClass,
+    snapshot,
+  });
+  return expanded;
+}
+
+export { MAX_EXPAND_FIELDS };

package/src/retry.js

@@ -0,0 +1,29 @@
+import { isRetryableDatabaseError } from './errors.js';
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withDatabaseRetry(operation, options = {}) {
+  const maxAttempts = options.maxAttempts ?? 3;
+  const baseDelayMs = options.baseDelayMs ?? 25;
+  const sleep = options.sleep ?? defaultSleep;
+
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) {
+    throw new Error('maxAttempts must be an integer between 1 and 10');
+  }
+
+  let attempt = 0;
+  while (attempt < maxAttempts) {
+    attempt += 1;
+
+    try {
+      return await operation({ attempt, maxAttempts });
+    } catch (error) {
+      if (!isRetryableDatabaseError(error) || attempt >= maxAttempts) throw error;
+      await sleep(baseDelayMs * attempt);
+    }
+  }
+
+  throw new Error('Database retry loop exited unexpectedly');
+}