@luca-financial/luca-schema 2.2.0 → 2.3.0

package/dist/esm/index.d.ts

@@ -553,7 +553,6 @@ export type Transaction = Common5 & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -623,10 +622,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID1 = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 /**
  * Defines a split within a transaction.
  */
@@ -1040,7 +1035,6 @@ export type Transaction = Common & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -1110,10 +1104,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 
 /**
  * Common properties for all schemas

package/dist/esm/index.js

@@ -1,6 +1,13 @@
 import * as schemaIndex from './schemas/index.js';
 import { enums, LucaSchemas } from './enums.js';
-import { validate } from './lucaValidator.js';
+import {
+  applyDefaults,
+  getRequiredFields,
+  getValidFields,
+  stripInvalidFields,
+  validate,
+  validateCollection
+} from './lucaValidator.js';
 
 const schemas = { ...schemaIndex, enums: schemaIndex.enums };
 
@@ -14,5 +21,15 @@ export const recurringTransactionEventSchema =
 export const transactionSchema = schemas.transaction;
 export const transactionSplitSchema = schemas.transactionSplit;
 
-export { enums, LucaSchemas, schemas, validate };
+export {
+  enums,
+  LucaSchemas,
+  schemas,
+  validate,
+  validateCollection,
+  getValidFields,
+  getRequiredFields,
+  stripInvalidFields,
+  applyDefaults
+};
 export default schemas;

package/dist/esm/lucaValidator.js

@@ -25,6 +25,8 @@ const schemas = {
 const supportSchemas = [commonSchemaJson, enumsSchemaJson];
 
 let sharedAjv;
+const validFieldsCache = new Map();
+const requiredFieldsCache = new Map();
 
 function getValidator() {
   if (sharedAjv) return sharedAjv;
@@ -46,14 +48,168 @@ function getValidator() {
   return sharedAjv;
 }
 
-export function validate(schemaKey, data) {
-  const ajv = getValidator();
+function getSchema(schemaKey) {
   const schema = schemas[schemaKey];
   if (!schema) {
     throw new Error(`Unknown schema: ${schemaKey}`);
   }
+  return schema;
+}
+
+function usesCommonSchema(schema) {
+  if (!Array.isArray(schema?.allOf)) return false;
+  return schema.allOf.some(entry => {
+    if (!entry || typeof entry !== 'object') return false;
+    if (typeof entry.$ref !== 'string') return false;
+    return entry.$ref.includes('common.json');
+  });
+}
+
+function getSchemaProperties(schema) {
+  const properties = schema?.properties ?? {};
+  if (!usesCommonSchema(schema)) return properties;
+  return {
+    ...commonSchemaJson.properties,
+    ...properties
+  };
+}
+
+function getSchemaRequired(schema) {
+  const required = Array.isArray(schema?.required) ? schema.required : [];
+  if (!usesCommonSchema(schema)) return required;
+  const commonRequired = Array.isArray(commonSchemaJson.required)
+    ? commonSchemaJson.required
+    : [];
+  return [...commonRequired, ...required];
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function cloneDefault(value) {
+  if (typeof structuredClone === 'function') return structuredClone(value);
+  if (value && typeof value === 'object') {
+    return JSON.parse(JSON.stringify(value));
+  }
+  return value;
+}
+
+export function validate(schemaKey, data) {
+  const ajv = getValidator();
+  const schema = getSchema(schemaKey);
   const isValid = ajv.validate(schema, data);
   return { valid: isValid, errors: ajv.errors ?? [] };
 }
 
+/**
+ * Returns a cached Set of valid field names for the given schema key.
+ * Treat the returned Set as read-only.
+ * @param {string} schemaKey
+ * @returns {Set<string>}
+ */
+export function getValidFields(schemaKey) {
+  if (validFieldsCache.has(schemaKey)) {
+    return validFieldsCache.get(schemaKey);
+  }
+  const schema = getSchema(schemaKey);
+  const properties = getSchemaProperties(schema);
+  const fields = new Set(Object.keys(properties));
+  validFieldsCache.set(schemaKey, fields);
+  return fields;
+}
+
+/**
+ * Returns a cached Set of required field names for the given schema key.
+ * Treat the returned Set as read-only.
+ * @param {string} schemaKey
+ * @returns {Set<string>}
+ */
+export function getRequiredFields(schemaKey) {
+  if (requiredFieldsCache.has(schemaKey)) {
+    return requiredFieldsCache.get(schemaKey);
+  }
+  const schema = getSchema(schemaKey);
+  const required = getSchemaRequired(schema);
+  const fields = new Set(required);
+  requiredFieldsCache.set(schemaKey, fields);
+  return fields;
+}
+
+/**
+ * Returns a new object containing only fields defined in the schema.
+ * @param {string} schemaKey
+ * @param {object | null | undefined} data
+ * @returns {object}
+ */
+export function stripInvalidFields(schemaKey, data) {
+  if (data === null || data === undefined) return {};
+  if (!isPlainObject(data)) {
+    throw new TypeError('Expected a plain object for data');
+  }
+  const validFields = getValidFields(schemaKey);
+  const cleaned = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (validFields.has(key)) cleaned[key] = value;
+  }
+  return cleaned;
+}
+
+/**
+ * Returns a new object with top-level schema defaults applied for missing fields.
+ * @param {string} schemaKey
+ * @param {object | null | undefined} data
+ * @returns {object}
+ */
+export function applyDefaults(schemaKey, data) {
+  if (data === null || data === undefined) return {};
+  if (!isPlainObject(data)) {
+    throw new TypeError('Expected a plain object for data');
+  }
+  const schema = getSchema(schemaKey);
+  const properties = getSchemaProperties(schema);
+  const next = { ...data };
+  for (const [key, definition] of Object.entries(properties)) {
+    if (next[key] !== undefined) continue;
+    if (
+      definition &&
+      Object.prototype.hasOwnProperty.call(definition, 'default')
+    ) {
+      next[key] = cloneDefault(definition.default);
+    }
+  }
+  return next;
+}
+
+/**
+ * Validates an array of entities efficiently and returns structured errors.
+ * @param {string} schemaKey
+ * @param {Array<any>} arrayOfEntities
+ * @returns {{ valid: boolean, errors: Array<{ index: number, entity: any, errors: Array<any> }> }}
+ */
+export function validateCollection(schemaKey, arrayOfEntities) {
+  if (!Array.isArray(arrayOfEntities)) {
+    throw new TypeError('Expected an array of entities');
+  }
+  const ajv = getValidator();
+  const schema = getSchema(schemaKey);
+  const validateFn = ajv.getSchema(schema.$id) ?? ajv.compile(schema);
+  const errors = [];
+
+  arrayOfEntities.forEach((entity, index) => {
+    const isValid = validateFn(entity);
+    if (!isValid) {
+      errors.push({
+        index,
+        entity,
+        errors: validateFn.errors ?? []
+      });
+    }
+  });
+
+  return { valid: errors.length === 0, errors };
+}
+
 export { schemas };

package/dist/esm/schemas/transaction.json

@@ -84,13 +84,6 @@
       "title": "Transaction State",
       "$ref": "./enums.json#/$defs/TransactionState",
       "description": "The current state of the transaction."
-    },
-    "deletedAt": {
-      "type": ["string", "null"],
-      "title": "Deleted At",
-      "format": "date-time",
-      "pattern": "Z$",
-      "description": "Timestamp when the transaction was soft-deleted, if applicable (UTC)."
     }
   },
   "required": ["accountId", "date", "amount", "description", "transactionState"]

package/dist/index.d.ts

@@ -553,7 +553,6 @@ export type Transaction = Common5 & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -623,10 +622,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID1 = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 /**
  * Defines a split within a transaction.
  */
@@ -1040,7 +1035,6 @@ export type Transaction = Common & {
     | 'DISPUTED'
     | 'REFUNDED'
     | 'DELETED';
-  deletedAt?: DeletedAt;
 };
 /**
  * UUID for the item
@@ -1110,10 +1104,6 @@ export type StatementID = string | null;
  * Identifier for this transaction in a financial data aggregation service.
  */
 export type AggregationServiceID = string | null;
-/**
- * Timestamp when the transaction was soft-deleted, if applicable (UTC).
- */
-export type DeletedAt = string | null;
 
 /**
  * Common properties for all schemas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luca-financial/luca-schema",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Schemas for the Luca Ledger application",
   "author": "Johnathan Aspinwall",
   "main": "dist/esm/index.js",