@railway-ts/pipelines 0.1.0

package/examples/result/result-examples.ts

@@ -0,0 +1,110 @@
+import { pipe } from '@/composition';
+import { ok, err, fromTry, match, flatMap, map, andThen, type Result } from '@/result';
+
+// Example 1: Division by Zero
+console.log('=== Division by Zero ===');
+
+// Problem: Division can fail but functions don't show it in types
+// function divide(a: number, b: number) {
+//   return a / b; // Returns Infinity for division by zero
+// }
+
+// Solution: Result makes failure explicit
+function safeDivide(a: number, b: number) {
+  return b === 0 ? err('Division by zero') : ok(a / b);
+}
+
+const result1 = safeDivide(10, 2);
+const result2 = safeDivide(10, 0);
+
+match(result1, {
+  ok: (value) => console.log(`Result: ${value}`),
+  err: (error) => console.log(`Error: ${error}`),
+}); // "Result: 5"
+
+match(result2, {
+  ok: (value) => console.log(`Result: ${value}`),
+  err: (error) => console.log(`Error: ${error}`),
+}); // "Error: Division by zero"
+
+// Example 2: JSON Parsing
+console.log('\n=== JSON Parsing ===');
+
+// Problem: JSON.parse throws exceptions
+// const data = JSON.parse('invalid json'); // Throws!
+
+// Solution: fromTry captures exceptions as Results
+const safeParseJson = (s: string) => fromTry(() => JSON.parse(s));
+
+const valid = safeParseJson('{"name": "Alice"}');
+const invalid = safeParseJson('invalid json');
+
+match(valid, {
+  ok: (data) => console.log(`Parsed: ${data.name}`),
+  err: (error) => console.log(`Parse failed: ${error}`),
+}); // "Parsed: Alice"
+
+match(invalid, {
+  ok: (data) => console.log(`Parsed: ${data.name}`),
+  err: (error) => console.log(`Parse failed: ${error}`),
+}); // "Parse failed: Unexpected token..."
+
+// Example 3: Chaining Operations
+console.log('\n=== Chaining Operations ===');
+
+// Problem: Multiple operations that can fail require nested try/catch
+// Solution: flatMapResult chains failing operations cleanly
+
+const hasNumericValue = (u: unknown): u is { value: number } =>
+  typeof u === 'object' && u !== null && 'value' in u && typeof (u as { value: unknown }).value === 'number';
+
+const toNumber = (data: unknown): Result<number, string> =>
+  hasNumericValue(data) ? ok(data.value) : err('Not a number');
+
+const processNumber = (input: string) =>
+  pipe(
+    safeParseJson(input),
+    (result) => flatMap(result, toNumber),
+    (result) => flatMap(result, (num) => safeDivide(num, 2)),
+    (result) => map(result, (num) => Math.round(num)),
+  );
+
+const success = processNumber('{"value": 42}');
+const failure = processNumber('{"value": "not a number"}');
+
+match(success, {
+  ok: (value) => console.log(`Final result: ${value}`),
+  err: (error) => console.log(`Failed: ${error}`),
+}); // "Final result: 21"
+
+match(failure, {
+  ok: (value) => console.log(`Final result: ${value}`),
+  err: (error) => console.log(`Failed: ${error}`),
+}); // "Failed: Not a number"
+
+// Example 4: Async Chaining with andThen
+console.log('\n=== Async Chaining ===');
+
+const safeDivideAsync = async (a: number, b: number): Promise<Result<number, string>> =>
+  b === 0 ? err('Division by zero') : ok(a / b);
+
+const processNumberAsync = async (input: string) =>
+  await pipe(
+    safeParseJson(input),
+    (r) => andThen(r, toNumber),
+    (p) => andThen(p, (n) => safeDivideAsync(n, 2)),
+    (p) => andThen(p, (n) => ok(Math.round(n))),
+  );
+
+const successAsync = await processNumberAsync('{"value": 42}');
+const failureAsync = await processNumberAsync('{"value": "not a number"}');
+
+match(successAsync, {
+  ok: (value) => console.log(`Async final result: ${value}`),
+  err: (error) => console.log(`Async failed: ${error}`),
+}); // "Async final result: 21"
+
+match(failureAsync, {
+  ok: (value) => console.log(`Async final result: ${value}`),
+  err: (error) => console.log(`Async failed: ${error}`),
+}); // "Async failed: Not a number"

package/examples/schema/basic.ts

@@ -0,0 +1,78 @@
+import {
+  array,
+  chain,
+  email,
+  matches,
+  minLength,
+  object,
+  optional,
+  parseBool,
+  parseDate,
+  parseNumber,
+  pattern,
+  required,
+  string,
+  stringEnum,
+  validateAndFormatResult,
+  nonEmpty,
+} from '@/schema';
+
+const invalidInput = {
+  username: 'jo', // too short
+  email: 'not-an-email', // invalid format
+  password: 'password', // not complex enough
+  age: '25', // string that will be parsed to a number
+  birthdate: '1995-05-15', // string that will be parsed to a Date
+  termsAccepted: 'yes', // string that will be parsed to boolean true
+  address: {
+    street: '123 Main St',
+    city: 'A', // too short
+    zipCode: '1234', // invalid format
+  },
+  contacts: ['email', 'phone', 'fax'], // fax is not a valid option
+};
+
+const validInput = {
+  username: 'john_doe',
+  email: 'valid@email.com',
+  password: 'ComplexPassword123!',
+  age: 30,
+  birthdate: new Date('1995-05-15'),
+  hasAcceptedTerms: true,
+  role: 'user',
+  address: {
+    street: '123 Main St',
+    city: 'New York',
+    zipCode: '10001',
+  },
+  contacts: ['email', 'phone'],
+};
+
+export const addressSchema = object({
+  street: optional(chain(string(), minLength(3))),
+  city: optional(chain(string(), minLength(2))),
+  zipCode: optional(chain(string(), pattern(/^\d{5}$/))),
+});
+
+export const userSchema = object({
+  username: required(chain(string(), nonEmpty(), minLength(3))),
+  email: required(chain(string(), nonEmpty(), email())),
+  password: required(chain(string(), nonEmpty(), minLength(8))),
+  age: required(parseNumber()),
+  birthdate: required(parseDate()),
+  hasAcceptedTerms: required(chain(parseBool(), matches(true, 'You must check this field'))),
+  role: required(stringEnum(['admin', 'user'])),
+  address: optional(addressSchema),
+  contacts: optional(array(stringEnum(['email', 'phone']))),
+});
+
+// Using validateAndFormatResult - one-liner convenience function
+const valid = validateAndFormatResult(validInput, userSchema);
+
+console.log('--- Valid User ---\n');
+console.log(valid);
+
+const invalid = validateAndFormatResult(invalidInput, userSchema);
+
+console.log('--- Invalid User ---\n');
+console.log(invalid);

package/examples/schema/union.ts

@@ -0,0 +1,301 @@
+import { match } from '@/result';
+import {
+  between,
+  boolean,
+  chain,
+  discriminatedUnion,
+  formatErrors,
+  literal,
+  object,
+  parseDate,
+  parseNumber,
+  pattern,
+  required,
+  string,
+  stringEnum,
+  validate,
+  type InferSchemaType,
+  type ValidationError,
+  type ValidationResult,
+} from '@/schema';
+
+// === Literal Constants ===
+export const ALERT_TYPES = {
+  ENGINE: 'engine',
+  HYDRAULIC: 'hydraulic',
+  ELECTRICAL: 'electrical',
+  FUEL: 'fuel',
+} as const;
+
+export const SEVERITY_LEVELS = ['warning', 'caution', 'advisory'] as const;
+export type SeverityLevel = (typeof SEVERITY_LEVELS)[number];
+
+export const ENGINE_NUMBERS = ['1', '2', '3', '4'] as const;
+export type EngineNumber = (typeof ENGINE_NUMBERS)[number];
+
+export const ENGINE_PARAMETERS = ['temperature', 'pressure', 'vibration', 'oil'] as const;
+export type EngineParameter = (typeof ENGINE_PARAMETERS)[number];
+
+export const HYDRAULIC_SYSTEMS = ['primary', 'backup', 'emergency'] as const;
+export type HydraulicSystem = (typeof HYDRAULIC_SYSTEMS)[number];
+
+export const ELECTRICAL_BUSES = ['main', 'essential', 'battery'] as const;
+export type ElectricalBus = (typeof ELECTRICAL_BUSES)[number];
+
+export const POWER_SOURCES = ['generator', 'apu', 'battery', 'external'] as const;
+export type PowerSource = (typeof POWER_SOURCES)[number];
+
+export const FUEL_TANKS = ['left_main', 'right_main', 'center', 'auxiliary'] as const;
+export type FuelTank = (typeof FUEL_TANKS)[number];
+
+// === Helper function to create common field definitions ===
+const createCommonFields = () => ({
+  timestamp: required(parseDate()),
+  aircraftId: required(chain(string(), pattern(/^[A-Z]-[A-Z0-9]{4,5}$/))), // e.g., N-12345, G-ABCD
+  flightNumber: required(chain(string(), pattern(/^[A-Z]{2,3}\d{1,4}$/))), // e.g., UA123, DLH4567
+  severity: required(stringEnum<SeverityLevel>([...SEVERITY_LEVELS], 'Invalid severity level')),
+  acknowledged: required(boolean()),
+});
+
+// === Engine Alert Schema ===
+const engineAlertSchema = object({
+  ...createCommonFields(),
+  type: required(literal(ALERT_TYPES.ENGINE)),
+  engineNumber: required(chain(stringEnum<EngineNumber>([...ENGINE_NUMBERS], 'Invalid engine number'), parseNumber())),
+  parameter: required(stringEnum<EngineParameter>([...ENGINE_PARAMETERS], 'Invalid engine parameter')),
+  value: required(chain(parseNumber(), between(0, 1000))),
+  threshold: required(chain(parseNumber(), between(0, 1000))),
+  exceedanceTime: required(chain(parseNumber(), between(0, 3600))),
+});
+
+// === Hydraulic System Alert Schema ===
+const hydraulicAlertSchema = object({
+  ...createCommonFields(),
+  type: required(literal(ALERT_TYPES.HYDRAULIC)),
+  system: required(stringEnum<HydraulicSystem>([...HYDRAULIC_SYSTEMS], 'Invalid hydraulic system')),
+  pressure: required(chain(parseNumber(), between(0, 5000))),
+  fluidLevel: required(chain(parseNumber(), between(0, 100))),
+  temperature: required(chain(parseNumber(), between(-50, 150))),
+});
+
+// === Electrical System Alert Schema ===
+const electricalAlertSchema = object({
+  ...createCommonFields(),
+  type: required(literal(ALERT_TYPES.ELECTRICAL)),
+  bus: required(stringEnum<ElectricalBus>([...ELECTRICAL_BUSES], 'Invalid electrical bus')),
+  voltage: required(chain(parseNumber(), between(0, 30))),
+  current: required(chain(parseNumber(), between(0, 200))),
+  source: required(stringEnum<PowerSource>([...POWER_SOURCES], 'Invalid power source')),
+  frequency: required(chain(parseNumber(), between(380, 420))),
+});
+
+// === Fuel System Alert Schema ===
+const fuelAlertSchema = object({
+  ...createCommonFields(),
+  type: required(literal(ALERT_TYPES.FUEL)),
+  tank: required(stringEnum<FuelTank>([...FUEL_TANKS], 'Invalid fuel tank')),
+  quantity: required(chain(parseNumber(), between(0, 50_000))),
+  imbalance: required(boolean()),
+  consumptionRate: required(chain(parseNumber(), between(0, 10_000))),
+  estimatedEndurance: required(chain(parseNumber(), between(0, 24))),
+});
+
+// === Type Definitions ===
+type EngineAlert = InferSchemaType<typeof engineAlertSchema>;
+type HydraulicAlert = InferSchemaType<typeof hydraulicAlertSchema>;
+type ElectricalAlert = InferSchemaType<typeof electricalAlertSchema>;
+type FuelAlert = InferSchemaType<typeof fuelAlertSchema>;
+
+type AlertTypes = EngineAlert | HydraulicAlert | ElectricalAlert | FuelAlert;
+
+// === Create Discriminated Union ===
+const completeAlertSchema = discriminatedUnion<AlertTypes>('type', {
+  [ALERT_TYPES.ENGINE]: engineAlertSchema,
+  [ALERT_TYPES.HYDRAULIC]: hydraulicAlertSchema,
+  [ALERT_TYPES.ELECTRICAL]: electricalAlertSchema,
+  [ALERT_TYPES.FUEL]: fuelAlertSchema,
+});
+
+type CompleteAlertSchema = InferSchemaType<typeof completeAlertSchema>;
+
+// Result type used in this example that includes extra display fields
+type AlertValidationDisplay = ValidationResult<CompleteAlertSchema> & {
+  summary?: string;
+  errorCount?: number;
+};
+
+// === Valid Data Examples ===
+const validEngineAlert = {
+  // Common fields
+  timestamp: new Date('2025-01-17T14:30:00Z'),
+  aircraftId: 'N-12345',
+  flightNumber: 'UA456',
+  severity: 'warning',
+  acknowledged: false,
+  // Engine-specific fields
+  type: ALERT_TYPES.ENGINE,
+  engineNumber: '2',
+  parameter: 'temperature',
+  value: 850,
+  threshold: 800,
+  exceedanceTime: 45,
+};
+
+const validHydraulicAlert = {
+  // Common fields
+  timestamp: new Date('2025-01-17T14:35:00Z'),
+  aircraftId: 'G-ABCD',
+  flightNumber: 'BA789',
+  severity: 'caution',
+  acknowledged: true,
+  // Hydraulic-specific fields
+  type: ALERT_TYPES.HYDRAULIC,
+  system: 'primary',
+  pressure: 2950,
+  fluidLevel: 85,
+  temperature: 45,
+};
+
+// === Invalid Data Examples ===
+const invalidAircraftIdPattern = {
+  timestamp: new Date('2025-01-17T14:40:00Z'),
+  aircraftId: '12345', // Missing prefix letter and dash
+  flightNumber: 'DL123',
+  severity: 'advisory',
+  acknowledged: false,
+  type: ALERT_TYPES.ELECTRICAL,
+  bus: 'main',
+  voltage: 28,
+  current: 50,
+  source: 'generator',
+  frequency: 400,
+};
+
+const invalidEngineNumber = {
+  timestamp: new Date('2025-01-17T14:45:00Z'),
+  aircraftId: 'N-98765',
+  flightNumber: 'AA100',
+  severity: 'warning',
+  acknowledged: false,
+  type: ALERT_TYPES.ENGINE,
+  engineNumber: '5', // Invalid engine number (only 1-4 allowed)
+  parameter: 'pressure',
+  value: 450,
+  threshold: 400,
+  exceedanceTime: 120,
+};
+
+const invalidFuelQuantity = {
+  timestamp: new Date('2025-01-17T14:50:00Z'),
+  aircraftId: 'C-FGHI',
+  flightNumber: 'AC202',
+  severity: 'caution',
+  acknowledged: true,
+  type: ALERT_TYPES.FUEL,
+  tank: 'center',
+  quantity: 75_000, // Exceeds maximum of 50_000 pounds
+  imbalance: true,
+  consumptionRate: 5000,
+  estimatedEndurance: 10,
+};
+
+const invalidAlertType = {
+  timestamp: new Date('2025-01-17T14:55:00Z'),
+  aircraftId: 'D-JKLM',
+  flightNumber: 'LH404',
+  severity: 'warning',
+  acknowledged: false,
+  type: 'navigation', // Invalid alert type
+  latitude: 45.5,
+  longitude: -73.5,
+};
+
+const missingCommonField = {
+  // Missing timestamp
+  aircraftId: 'F-NOPQ',
+  flightNumber: 'AF505',
+  severity: 'advisory',
+  acknowledged: false,
+  type: ALERT_TYPES.HYDRAULIC,
+  system: 'backup',
+  pressure: 3000,
+  fluidLevel: 90,
+  temperature: 25,
+};
+
+const extraFieldsInjection = {
+  // Test that extra fields are rejected
+  timestamp: new Date('2025-01-17T15:00:00Z'),
+  aircraftId: 'N-54321',
+  flightNumber: 'UA999',
+  severity: 'warning',
+  acknowledged: false,
+  type: ALERT_TYPES.ENGINE,
+  engineNumber: '1',
+  parameter: 'temperature',
+  value: 750,
+  threshold: 700,
+  exceedanceTime: 30,
+  // Attempting to inject extra fields
+  maliciousField: 'should-be-rejected',
+  __proto__: { injected: true },
+  constructor: { name: 'hack' },
+};
+
+// === Validation Function ===
+const processValidation = (data: unknown) => {
+  const validationResult = validate(data, completeAlertSchema);
+  return match<CompleteAlertSchema, ValidationError[], AlertValidationDisplay>(validationResult, {
+    ok: (validData) => ({
+      valid: true,
+      data: validData,
+      summary: `Alert processed: ${validData.type} on ${validData.aircraftId} (${validData.severity})`,
+    }),
+    err: (errors) => ({
+      valid: false,
+      errors: formatErrors(errors),
+      errorCount: errors.length,
+    }),
+  });
+};
+
+// === Process and Log Results ===
+
+console.log('=== Aircraft System Alert Validation Examples ===\n');
+
+console.log('--- Valid Engine Alert ---');
+const validEngineResult = processValidation(validEngineAlert);
+console.log(validEngineResult);
+
+console.log('--- Valid Hydraulic Alert ---');
+const validHydraulicResult = processValidation(validHydraulicAlert);
+console.log(validHydraulicResult);
+
+console.log('--- Invalid: Bad Aircraft ID Pattern ---');
+const invalidPatternResult = processValidation(invalidAircraftIdPattern);
+console.log(invalidPatternResult);
+
+console.log('--- Invalid: Engine Number Out of Range ---');
+const invalidEngineResult = processValidation(invalidEngineNumber);
+console.log(invalidEngineResult);
+
+console.log('--- Invalid: Fuel Quantity Exceeds Limit ---');
+const invalidFuelResult = processValidation(invalidFuelQuantity);
+console.log(invalidFuelResult);
+
+console.log('--- Invalid: Unknown Alert Type ---');
+const invalidTypeResult = processValidation(invalidAlertType);
+console.log(invalidTypeResult);
+
+console.log('--- Invalid: Missing Common Field (timestamp) ---');
+const missingFieldResult = processValidation(missingCommonField);
+console.log(missingFieldResult);
+
+console.log('--- Security Test: Extra Fields Injection ---');
+const injectionResult = processValidation(extraFieldsInjection);
+// After your processValidation call
+console.log('--- Prototype Pollution Check ---');
+console.log("Does a fresh object have 'injected'? ->", ({} as any).injected); // undefined
+console.log("Does Object.prototype have 'injected'? ->", (Object.prototype as any).injected); // undefined
+console.log(injectionResult);
+console.log('Note: Extra fields should be rejected in strict mode');

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@railway-ts/pipelines",
+  "version": "0.1.0",
+  "description": "Functional programming abstractions for TypeScript: Build robust data pipelines with schema validation, Option, Result, and railway-oriented programming.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./option": {
+      "types": "./dist/option/index.d.ts",
+      "import": "./dist/option/index.mjs",
+      "require": "./dist/option/index.cjs"
+    },
+    "./result": {
+      "types": "./dist/result/index.d.ts",
+      "import": "./dist/result/index.mjs",
+      "require": "./dist/result/index.cjs"
+    },
+    "./composition": {
+      "types": "./dist/composition/index.d.ts",
+      "import": "./dist/composition/index.mjs",
+      "require": "./dist/composition/index.cjs"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.mjs",
+      "require": "./dist/schema/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples"
+  ],
+  "scripts": {
+    "build": "bunx tsup",
+    "build:watch": "bunx tsup --watch",
+    "dev": "bunx tsup --watch",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:coverage:lcov": "mkdir -p coverage && bun test --coverage --coverage-reporter=lcov",
+    "test:bail": "bun test --bail",
+    "test:fast": "bun test --bail --timeout=1000",
+    "test:pattern": "bun test --test-name-pattern",
+    "test:only": "bun test --only",
+    "test:reporter": "bun test --reporter=junit --reporter-outfile=junit.xml",
+    "lint": "bunx eslint .",
+    "lint:fix": "bunx eslint . --fix",
+    "format": "bunx prettier --write .",
+    "format:check": "bunx prettier --check .",
+    "typecheck": "bunx tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun run lint && bun run test && bun run build",
+    "check": "bun run typecheck && bun run lint && bun run test"
+  },
+  "keywords": [
+    "typescript",
+    "functional",
+    "option",
+    "result",
+    "railway",
+    "monads",
+    "schema",
+    "pipeline"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sakobu/railway-ts-pipelines.git"
+  },
+  "homepage": "https://github.com/sakobu/railway-ts-pipelines#readme",
+  "bugs": {
+    "url": "https://github.com/sakobu/railway-ts-pipelines/issues"
+  },
+  "sideEffects": false,
+  "author": "Sarkis Melkonian",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "@types/bun": "latest",
+    "eslint": "^9.36.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-security": "^3.0.1",
+    "eslint-plugin-unicorn": "^61.0.2",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript-eslint": "^8.44.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}