@toiroakr/lines-db 0.5.0 → 0.6.0

package/src/schema.ts

@@ -2,8 +2,9 @@ import type { StandardSchema, Table, ForeignKeyDefinition, IndexDefinition } fro
 
 /**
  * Schema options for defining constraints and indexes
+ * When Input and Output types differ, backward transformation is required
  */
-export interface SchemaOptions {
+export type SchemaOptions<Input extends Table, Output extends Table> = {
   /**
    * Primary key column
    */
@@ -18,13 +19,19 @@ export interface SchemaOptions {
    * Indexes to create
    */
   indexes?: IndexDefinition[];
-
-  /**
-   * Backward transformation from Output to Input
-   * Required when Input and Output types differ (e.g., with transformations)
-   */
-  backward?: (output: Table) => Table;
-}
+} & (Output extends Input
+  ? {
+      /**
+       * Backward transformation from Output to Input (optional when output is substitutable for input)
+       */
+      backward?: (output: Output) => Input;
+    }
+  : {
+      /**
+       * Backward transformation from Output to Input (REQUIRED when types differ)
+       */
+      backward: (output: Output) => Input;
+    });
 
 /**
  * BiDirectional Schema interface
@@ -58,8 +65,7 @@ export interface BiDirectionalSchema<Input extends Table = Table, Output extends
  * Define a bidirectional schema with optional backward transformation
  *
  * @param schema - Standard Schema for validation
- * @param optionsOrBackward - Optional SchemaOptions object or backward transformation function (Output → Input)
- *                            Required when schema performs transformations
+ * @param options - SchemaOptions object. When Input and Output types differ, backward transformation is required
  *
  * @example
  * // No transformation - backward not needed
@@ -68,10 +74,12 @@ export interface BiDirectionalSchema<Input extends Table = Table, Output extends
  * );
  *
  * @example
- * // With transformation - backward recommended (legacy)
+ * // With transformation - backward REQUIRED
  * const schema = defineSchema(
  *   v.pipe(v.string(), v.transform(Number)),
- *   (num) => String(num)  // backward: number → string
+ *   {
+ *     backward: (num) => String(num)  // backward: number → string (REQUIRED)
+ *   }
  * );
  *
  * @example
@@ -88,30 +96,27 @@ export interface BiDirectionalSchema<Input extends Table = Table, Output extends
  */
 export function defineSchema<Input extends Table, Output extends Table>(
   schema: StandardSchema<Input, Output>,
-  optionsOrBackward?: SchemaOptions | ((output: Output) => Input),
+  ...args: Output extends Input
+    ? [options?: SchemaOptions<Input, Output>]
+    : [options: SchemaOptions<Input, Output>]
 ): BiDirectionalSchema<Input, Output> {
+  const options = args[0];
   // Create a new object that extends the schema
   const bidirectionalSchema = Object.create(schema) as BiDirectionalSchema<Input, Output>;
 
-  // Handle options or backward function
-  if (optionsOrBackward) {
-    if (typeof optionsOrBackward === 'function') {
-      // Legacy: backward function only
-      bidirectionalSchema.backward = optionsOrBackward;
-    } else {
-      // New: options object
-      if (optionsOrBackward.backward) {
-        bidirectionalSchema.backward = optionsOrBackward.backward as (output: Output) => Input;
-      }
-      if (optionsOrBackward.primaryKey) {
-        bidirectionalSchema.primaryKey = optionsOrBackward.primaryKey;
-      }
-      if (optionsOrBackward.foreignKeys) {
-        bidirectionalSchema.foreignKeys = optionsOrBackward.foreignKeys;
-      }
-      if (optionsOrBackward.indexes) {
-        bidirectionalSchema.indexes = optionsOrBackward.indexes;
-      }
+  // Handle options object
+  if (options) {
+    if (options.backward) {
+      bidirectionalSchema.backward = options.backward as (output: Output) => Input;
+    }
+    if (options.primaryKey) {
+      bidirectionalSchema.primaryKey = options.primaryKey;
+    }
+    if (options.foreignKeys) {
+      bidirectionalSchema.foreignKeys = options.foreignKeys;
+    }
+    if (options.indexes) {
+      bidirectionalSchema.indexes = options.indexes;
     }
   }
 

package/src/types.ts

@@ -17,6 +17,27 @@ export type { StandardSchemaV1 };
 export type InferInput<T> = T extends StandardSchemaV1<infer I, unknown> ? I : never;
 export type InferOutput<T> = T extends StandardSchemaV1<unknown, infer O> ? O : never;
 
+// Validation result types
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationErrorDetail[];
+  warnings: string[];
+}
+
+export interface ValidationErrorDetail {
+  file: string;
+  tableName: string;
+  rowIndex: number;
+  issues: ReadonlyArray<StandardSchemaIssue>;
+  type?: 'schema' | 'foreignKey';
+  foreignKeyError?: {
+    column: string;
+    value: unknown;
+    referencedTable: string;
+    referencedColumn: string;
+  };
+}
+
 export interface ForeignKeyDefinition {
   column: string;
   references: {

package/src/validator.test.ts

@@ -1,507 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { Validator } from './validator.js';
-import { writeFile, mkdir, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-
-describe('Validator', () => {
-  let testDir: string;
-
-  beforeEach(async () => {
-    testDir = join(tmpdir(), `validator-test-${Date.now()}`);
-    await mkdir(testDir, { recursive: true });
-  });
-
-  afterEach(async () => {
-    await rm(testDir, { recursive: true, force: true });
-  });
-
-  describe('validate file', () => {
-    it('should validate file with valid data', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      await writeFile(jsonlPath, '{"id":1,"name":"Alice"}\n{"id":2,"name":"Bob"}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => {
-              const issues = [];
-              if (!data.id || !data.name) {
-                issues.push({ message: 'Missing required fields' });
-              }
-              return { value: data, issues };
-            }
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(true);
-      expect(result.errors).toHaveLength(0);
-      expect(result.warnings).toHaveLength(0);
-    });
-
-    it('should detect validation errors', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      await writeFile(jsonlPath, '{"id":1,"name":"Alice"}\n{"id":2}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => {
-              const issues = [];
-              if (!data.name) {
-                issues.push({ message: 'Missing name field', path: ['name'] });
-              }
-              return { value: data, issues };
-            }
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].rowIndex).toBe(1); // 0-indexed: line 2 is index 1
-      expect(result.errors[0].tableName).toBe('users');
-      expect(result.errors[0].issues).toHaveLength(1);
-    });
-
-    it('should throw when no schema exists', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      await writeFile(jsonlPath, '{"id":1}\n{"id":2}\n');
-
-      const validator = new Validator({ path: jsonlPath });
-      await expect(validator.validate()).rejects.toThrow(/Schema file not found/);
-    });
-
-    it('should handle multiple validation errors in single file', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      await writeFile(jsonlPath, '{"id":1}\n{"id":2}\n{"id":3,"name":"Charlie"}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => {
-              const issues = [];
-              if (!data.name) {
-                issues.push({ message: 'Missing name' });
-              }
-              return { value: data, issues };
-            }
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(2);
-      expect(result.errors[0].rowIndex).toBe(0); // 0-indexed: line 1 is index 0
-      expect(result.errors[1].rowIndex).toBe(1); // 0-indexed: line 2 is index 1
-    });
-
-    it('should return 0-based rowIndex (first line = index 0)', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      // Line 1: valid, Line 2: invalid (no name), Line 3: invalid (no name)
-      await writeFile(jsonlPath, '{"id":1,"name":"Alice"}\n{"id":2}\n{"id":3}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => {
-              const issues = [];
-              if (!data.name) {
-                issues.push({ message: 'Missing name field', path: ['name'] });
-              }
-              return { value: data, issues };
-            }
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(2);
-      // First error is on line 2 of the file, which is index 1 (0-based)
-      expect(result.errors[0].rowIndex).toBe(1);
-      expect(result.errors[0].file).toBe(jsonlPath);
-      // Second error is on line 3 of the file, which is index 2 (0-based)
-      expect(result.errors[1].rowIndex).toBe(2);
-      expect(result.errors[1].file).toBe(jsonlPath);
-    });
-
-    it('should return 0-based rowIndex for first line error', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      // First line has error
-      await writeFile(jsonlPath, '{"id":1}\n{"id":2,"name":"Bob"}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => {
-              const issues = [];
-              if (!data.name) {
-                issues.push({ message: 'Missing name field', path: ['name'] });
-              }
-              return { value: data, issues };
-            }
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      // First line (line 1 in file) should be index 0
-      expect(result.errors[0].rowIndex).toBe(0);
-      expect(result.errors[0].file).toBe(jsonlPath);
-    });
-  });
-
-  describe('validate directory', () => {
-    it('should validate all JSONL files in directory', async () => {
-      const usersPath = join(testDir, 'users.jsonl');
-      const productsPath = join(testDir, 'products.jsonl');
-      const usersSchemaPath = join(testDir, 'users.schema.ts');
-      const productsSchemaPath = join(testDir, 'products.schema.ts');
-
-      await writeFile(usersPath, '{"id":1,"name":"Alice"}\n');
-      await writeFile(productsPath, '{"id":1,"name":"Product"}\n');
-      await writeFile(
-        usersSchemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          }
-        };
-      `,
-      );
-      await writeFile(
-        productsSchemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: testDir });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(true);
-      expect(result.errors).toHaveLength(0);
-      expect(result.warnings).toHaveLength(0);
-    });
-
-    it('should collect errors from multiple files', async () => {
-      const usersPath = join(testDir, 'users.jsonl');
-      const usersSchemaPath = join(testDir, 'users.schema.ts');
-      const productsPath = join(testDir, 'products.jsonl');
-      const productsSchemaPath = join(testDir, 'products.schema.ts');
-
-      await writeFile(usersPath, '{"id":1}\n');
-      await writeFile(
-        usersSchemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({
-              value: data,
-              issues: data.name ? [] : [{ message: 'Missing name' }]
-            })
-          }
-        };
-      `,
-      );
-
-      await writeFile(productsPath, '{"id":1}\n');
-      await writeFile(
-        productsSchemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({
-              value: data,
-              issues: data.price ? [] : [{ message: 'Missing price' }]
-            })
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: testDir });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(2);
-    });
-
-    it('should throw error for directory with no JSONL files', async () => {
-      await writeFile(join(testDir, 'readme.txt'), 'no jsonl files here');
-
-      const validator = new Validator({ path: testDir });
-
-      await expect(validator.validate()).rejects.toThrow('No JSONL files found');
-    });
-
-    it('should skip validation and warn for JSONL files without schema', async () => {
-      const usersPath = join(testDir, 'users.jsonl');
-      const productsPath = join(testDir, 'products.jsonl');
-      const usersSchemaPath = join(testDir, 'users.schema.ts');
-
-      // Only users.jsonl has a schema
-      await writeFile(usersPath, '{"id":1,"name":"Alice"}\n');
-      await writeFile(productsPath, '{"id":1,"name":"Product"}\n');
-      await writeFile(
-        usersSchemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: testDir });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(true);
-      expect(result.errors).toHaveLength(0);
-      expect(result.warnings).toHaveLength(1);
-      expect(result.warnings[0]).toContain('products');
-      expect(result.warnings[0]).toContain('schema file not found');
-    });
-  });
-
-  describe('error handling', () => {
-    it('should throw error for non-JSONL file', async () => {
-      const txtPath = join(testDir, 'test.txt');
-      await writeFile(txtPath, 'not a jsonl file');
-
-      const validator = new Validator({ path: txtPath });
-
-      await expect(validator.validate()).rejects.toThrow('Invalid path');
-    });
-
-    it('should reject async validation', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      await writeFile(jsonlPath, '{"id":1}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: async (data) => {
-              return { value: data, issues: [] };
-            }
-          }
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-
-      await expect(validator.validate()).rejects.toThrow(
-        'Asynchronous validation is not supported',
-      );
-    });
-  });
-
-  describe('constraint validation', () => {
-    it('should detect primary key constraint violations', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      // Write data with duplicate id
-      await writeFile(
-        jsonlPath,
-        '{"id":"1","name":"Alice","email":"alice@example.com"}\n{"id":"1","name":"Bob","email":"bob@example.com"}\n',
-      );
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          },
-          primaryKey: 'id'
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].rowIndex).toBe(1);
-      expect(result.errors[0].issues[0].message).toContain('UNIQUE constraint failed');
-      expect(result.errors[0].issues[0].message).toContain('id');
-    });
-
-    it('should detect unique index constraint violations', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      // Write data with duplicate email
-      await writeFile(
-        jsonlPath,
-        '{"id":"1","name":"Alice","email":"alice@example.com"}\n{"id":"2","name":"Bob","email":"alice@example.com"}\n',
-      );
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          },
-          primaryKey: 'id',
-          indexes: [
-            { name: 'users_email_unique', columns: ['email'], unique: true }
-          ]
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].rowIndex).toBe(1);
-      expect(result.errors[0].issues[0].message).toContain('UNIQUE constraint failed');
-      expect(result.errors[0].issues[0].message).toContain('email');
-    });
-
-    it('should use id column as primary key when primaryKey is not specified', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      // Write data with duplicate id (no primaryKey specified in schema)
-      await writeFile(jsonlPath, '{"id":"1","name":"Alice"}\n{"id":"1","name":"Bob"}\n');
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          }
-          // Note: no primaryKey specified
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].rowIndex).toBe(1);
-      expect(result.errors[0].issues[0].message).toContain('UNIQUE constraint failed');
-      expect(result.errors[0].issues[0].message).toContain('id');
-    });
-
-    it('should detect multiple constraint violations in single file', async () => {
-      const jsonlPath = join(testDir, 'users.jsonl');
-      const schemaPath = join(testDir, 'users.schema.ts');
-
-      // Write data with both duplicate id and duplicate email
-      await writeFile(
-        jsonlPath,
-        '{"id":"1","name":"Alice","email":"alice@example.com"}\n{"id":"1","name":"Bob","email":"bob@example.com"}\n{"id":"2","name":"Charlie","email":"alice@example.com"}\n',
-      );
-      await writeFile(
-        schemaPath,
-        `
-        export const schema = {
-          '~standard': {
-            version: 1,
-            vendor: 'test',
-            validate: (data) => ({ value: data, issues: [] })
-          },
-          primaryKey: 'id',
-          indexes: [
-            { name: 'users_email_unique', columns: ['email'], unique: true }
-          ]
-        };
-      `,
-      );
-
-      const validator = new Validator({ path: jsonlPath });
-      const result = await validator.validate();
-
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(2);
-      // First error: duplicate id
-      expect(result.errors[0].rowIndex).toBe(1);
-      expect(result.errors[0].issues[0].message).toContain('id');
-      // Second error: duplicate email
-      expect(result.errors[1].rowIndex).toBe(2);
-      expect(result.errors[1].issues[0].message).toContain('email');
-    });
-  });
-});