@pgflow/dsl 0.0.5-prealpha.2 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgflow/dsl",
-  "version": "0.0.5-prealpha.2",
+  "version": "0.0.6",
   "dependencies": {
     "vitest": "*"
   },
@@ -15,6 +15,9 @@
       "import": "./dist/index.js"
     }
   },
+  "files": [
+    "dist"
+  ],
   "types": "./dist/index.d.ts",
   "type": "module",
   "publishConfig": {

package/__tests__/runtime/flow.test.ts

@@ -1,121 +0,0 @@
-import { describe, it, vi, expect } from 'vitest';
-import { Flow } from '../../src/dsl.ts';
-import * as utils from '../../src/utils.ts';
-
-const noop = () => null;
-
-describe('Flow', () => {
-  describe('constructor', () => {
-    it('creates a flow with valid defaults', () => {
-      const flow = new Flow({ slug: 'valid_flow' });
-      expect(flow.slug).toBe('valid_flow');
-      expect(flow.options).toEqual({});
-    });
-
-    it('creates a flow with custom runtime options', () => {
-      const flow = new Flow({
-        slug: 'custom_flow',
-        maxAttempts: 3,
-        baseDelay: 100,
-        timeout: 30,
-      });
-      expect(flow.slug).toBe('custom_flow');
-      expect(flow.options).toEqual({
-        maxAttempts: 3,
-        baseDelay: 100,
-        timeout: 30,
-      });
-    });
-  });
-
-  describe('slug validation', () => {
-    it('calls validateSlug with the correct slug', () => {
-      const validateSlugSpy = vi.spyOn(utils, 'validateSlug');
-      new Flow({ slug: 'hello_world' });
-      expect(validateSlugSpy).toHaveBeenCalledWith('hello_world');
-      validateSlugSpy.mockRestore();
-    });
-
-    it('propagates errors from validateSlug', () => {
-      const validateSlugSpy = vi.spyOn(utils, 'validateSlug');
-      validateSlugSpy.mockImplementation(() => {
-        throw new Error('Mock validation error');
-      });
-      expect(() => new Flow({ slug: 'test' })).toThrowError(
-        'Mock validation error'
-      );
-      validateSlugSpy.mockRestore();
-    });
-
-    // Integration tests for invalid slugs
-    it('rejects invalid slugs during flow creation', () => {
-      expect(() => new Flow({ slug: '1invalid' })).toThrowError();
-    });
-  });
-
-  describe('runtime options validation', () => {
-    it('calls validateRuntimeOptions with the correct options', () => {
-      const validateRuntimeOptionsSpy = vi.spyOn(
-        utils,
-        'validateRuntimeOptions'
-      );
-      new Flow({
-        slug: 'test_flow',
-        maxAttempts: 3,
-        baseDelay: 100,
-        timeout: 30,
-      });
-      expect(validateRuntimeOptionsSpy).toHaveBeenCalledWith(
-        { maxAttempts: 3, baseDelay: 100, timeout: 30 },
-        { optional: true }
-      );
-      validateRuntimeOptionsSpy.mockRestore();
-    });
-
-    it('propagates errors from validateRuntimeOptions', () => {
-      const validateRuntimeOptionsSpy = vi.spyOn(
-        utils,
-        'validateRuntimeOptions'
-      );
-      validateRuntimeOptionsSpy.mockImplementation(() => {
-        throw new Error('Mock validation error');
-      });
-      expect(
-        () => new Flow({ slug: 'test_flow', maxAttempts: 0 })
-      ).toThrowError('Mock validation error');
-      validateRuntimeOptionsSpy.mockRestore();
-    });
-  });
-
-  describe('getStepDefinition', () => {
-    it('returns the root step definition when step exists', () => {
-      const flow = new Flow<{ value: number }>({ slug: 'test_flow' }).step(
-        { slug: 'root_step' },
-        noop
-      );
-
-      const stepDef = flow.getStepDefinition('root_step');
-      expect(stepDef.slug).toBe('root_step');
-      expect(stepDef.dependencies).toEqual([]);
-    });
-
-    it('returns the normal step definition when step exists', () => {
-      const flow = new Flow<{ value: number }>({ slug: 'test_flow' })
-        .step({ slug: 'root_step' }, noop)
-        .step({ slug: 'last_step', dependsOn: ['root_step'] }, noop);
-
-      const stepDef = flow.getStepDefinition('last_step');
-      expect(stepDef.slug).toBe('last_step');
-      expect(stepDef.dependencies).toEqual(['root_step']);
-    });
-
-    it('throws error when step does not exist', () => {
-      const flow = new Flow<{ value: number }>({ slug: 'test_flow' });
-
-      // @ts-expect-error - intentionally testing invalid slug
-      expect(() => flow.getStepDefinition('non_existent')).toThrowError(
-        'Step "non_existent" does not exist in flow "test_flow"'
-      );
-    });
-  });
-});

package/__tests__/runtime/steps.test.ts

@@ -1,183 +0,0 @@
-import { describe, it, vi, beforeEach, expect } from 'vitest';
-import { Flow } from '../../src/dsl.ts';
-import * as utils from '../../src/utils.ts';
-
-describe('Steps', () => {
-  let flow: Flow<any>;
-  const noop = () => null;
-
-  beforeEach(() => {
-    flow = new Flow({ slug: 'test_flow' });
-  });
-
-  describe('step addition', () => {
-    it('adds a step with the correct handler', () => {
-      const handler = () => ({ result: 42 });
-      const newFlow = flow.step({ slug: 'test_step' }, handler);
-
-      expect(newFlow.getStepDefinition('test_step').handler).toBe(handler);
-    });
-
-    it('throws when adding step with the same slug', () => {
-      const newFlow = flow.step({ slug: 'test_step' }, noop);
-
-      expect(() => newFlow.step({ slug: 'test_step' }, noop)).toThrowError(
-        'Step "test_step" already exists in flow "test_flow"'
-      );
-    });
-  });
-
-  describe('slug validation', () => {
-    it('calls validateSlug with the correct slug', () => {
-      const validateSlugSpy = vi.spyOn(utils, 'validateSlug');
-      flow.step({ slug: 'test_step' }, noop);
-      expect(validateSlugSpy).toHaveBeenCalledWith('test_step');
-      validateSlugSpy.mockRestore();
-    });
-
-    it('propagates errors from validateSlug', () => {
-      const validateSlugSpy = vi.spyOn(utils, 'validateSlug');
-      validateSlugSpy.mockImplementation(() => {
-        throw new Error('Mock validation error');
-      });
-      expect(() => flow.step({ slug: 'test' }, noop)).toThrowError(
-        'Mock validation error'
-      );
-      validateSlugSpy.mockRestore();
-    });
-  });
-
-  describe('dependencies', () => {
-    it('can add step without dependencies', () => {
-      expect(() => flow.step({ slug: 'no_deps' }, noop)).not.toThrowError();
-    });
-
-    it('can add step with explicit empty array of dependencies', () => {
-      expect(() =>
-        flow.step({ slug: 'empty_deps', dependsOn: [] }, noop)
-      ).not.toThrowError();
-    });
-
-    it('allows adding step with valid dependencies', () => {
-      const newFlow = flow.step({ slug: 'first_step' }, noop);
-
-      expect(() =>
-        newFlow.step({ slug: 'second_step', dependsOn: ['first_step'] }, noop)
-      ).not.toThrowError();
-    });
-
-    it('does not allow adding step with non-existing dependencies', () => {
-      expect(() =>
-        flow.step(
-          // @ts-expect-error - dependsOn references non-existing step
-          { slug: 'invalid_deps', dependsOn: ['non_existing_step'] },
-          noop
-        )
-      ).toThrowError(
-        'Step "invalid_deps" depends on undefined step "non_existing_step"'
-      );
-    });
-
-    it('does not allow adding step with non-string dependencies', () => {
-      expect(() =>
-        // @ts-expect-error - dependsOn contains non-string value
-        flow.step({ slug: 'invalid_deps', dependsOn: [12345] }, noop)
-      ).toThrowError('Step "invalid_deps" depends on undefined step "12345"');
-    });
-  });
-
-  describe('runtime options', () => {
-    it('calls validateRuntimeOptions with the correct options', () => {
-      const validateRuntimeOptionsSpy = vi.spyOn(
-        utils,
-        'validateRuntimeOptions'
-      );
-      flow.step(
-        {
-          slug: 'test_step',
-          maxAttempts: 3,
-          baseDelay: 100,
-          timeout: 30,
-        },
-        noop
-      );
-      expect(validateRuntimeOptionsSpy).toHaveBeenCalledWith(
-        { maxAttempts: 3, baseDelay: 100, timeout: 30 },
-        { optional: true }
-      );
-      validateRuntimeOptionsSpy.mockRestore();
-    });
-
-    it('propagates errors from validateRuntimeOptions', () => {
-      const validateRuntimeOptionsSpy = vi.spyOn(
-        utils,
-        'validateRuntimeOptions'
-      );
-      validateRuntimeOptionsSpy.mockImplementation(() => {
-        throw new Error('Mock validation error');
-      });
-      expect(() =>
-        flow.step(
-          {
-            slug: 'test_step',
-            maxAttempts: 0,
-          },
-          noop
-        )
-      ).toThrowError('Mock validation error');
-      validateRuntimeOptionsSpy.mockRestore();
-    });
-
-    it('stores runtime options on the step definition', () => {
-      const newFlow = flow.step(
-        {
-          slug: 'test_step',
-          maxAttempts: 3,
-          baseDelay: 100,
-          timeout: 30,
-        },
-        noop
-      );
-
-      const stepDef = newFlow.getStepDefinition('test_step');
-      expect(stepDef.options).toEqual({
-        maxAttempts: 3,
-        baseDelay: 100,
-        timeout: 30,
-      });
-    });
-  });
-
-  describe('step integration', () => {
-    it('allows steps to access run input', async () => {
-      const testFlow = new Flow<{ value: number }>({ slug: 'test_flow' }).step(
-        { slug: 'step1' },
-        ({ run }) => ({ doubled: run.value * 2 })
-      );
-
-      const step1Def = testFlow.getStepDefinition('step1');
-      const result = await step1Def.handler({ run: { value: 5 } });
-
-      expect(result).toEqual({ doubled: 10 });
-    });
-
-    it('allows steps to access dependencies', async () => {
-      const testFlow = new Flow<{ value: number }>({ slug: 'test_flow' })
-        .step({ slug: 'step1' }, ({ run }) => ({ doubled: run.value * 2 }))
-        .step({ slug: 'step2', dependsOn: ['step1'] }, ({ step1 }) => ({
-          quadrupled: step1.doubled * 2,
-        }));
-
-      const step1Def = testFlow.getStepDefinition('step1');
-      const step1Result = await step1Def.handler({ run: { value: 5 } });
-
-      const step2Def = testFlow.getStepDefinition('step2');
-      const step2Result = await step2Def.handler({
-        run: { value: 5 },
-        step1: step1Result,
-      });
-
-      expect(step2Result).toEqual({ quadrupled: 20 });
-    });
-  });
-});

package/__tests__/runtime/utils.test.ts

@@ -1,149 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { validateSlug, validateRuntimeOptions } from '../../src/utils.ts';
-
-describe('validateSlug', () => {
-  it('accepts valid slugs', () => {
-    expect(() => validateSlug('valid_slug')).not.toThrowError();
-    expect(() => validateSlug('valid_slug_123')).not.toThrowError();
-    expect(() => validateSlug('validSlug123')).not.toThrowError();
-  });
-
-  it('rejects slugs that start with numbers', () => {
-    expect(() => validateSlug('1invalid')).toThrowError(
-      'Slug cannot start with a number'
-    );
-  });
-
-  it('rejects slugs that start with underscores', () => {
-    expect(() => validateSlug('_invalid')).toThrowError(
-      'Slug cannot start with an underscore'
-    );
-  });
-
-  it('rejects slugs containing spaces', () => {
-    expect(() => validateSlug('invalid slug')).toThrowError(
-      'Slug cannot contain spaces'
-    );
-  });
-
-  it('rejects slugs containing special characters', () => {
-    expect(() => validateSlug('invalid/slug')).toThrowError(
-      'Slug cannot contain special characters like /, :, ?, #, -'
-    );
-    expect(() => validateSlug('invalid:slug')).toThrowError(
-      'Slug cannot contain special characters like /, :, ?, #, -'
-    );
-    expect(() => validateSlug('invalid?slug')).toThrowError(
-      'Slug cannot contain special characters like /, :, ?, #, -'
-    );
-    expect(() => validateSlug('invalid#slug')).toThrowError(
-      'Slug cannot contain special characters like /, :, ?, #, -'
-    );
-    expect(() => validateSlug('invalid-slug')).toThrowError(
-      'Slug cannot contain special characters like /, :, ?, #, -'
-    );
-  });
-
-  it('rejects slugs longer than 128 characters', () => {
-    const longSlug = 'a'.repeat(129);
-    expect(() => validateSlug(longSlug)).toThrowError(
-      'Slug cannot be longer than 128 characters'
-    );
-  });
-});
-
-describe('validateRuntimeOptions', () => {
-  describe('when optional is false (default)', () => {
-    it('throws when required options are missing', () => {
-      expect(() => validateRuntimeOptions({})).toThrowError(
-        'maxAttempts is required'
-      );
-      expect(() => validateRuntimeOptions({ maxAttempts: 1 })).toThrowError(
-        'baseDelay is required'
-      );
-      expect(() =>
-        validateRuntimeOptions({ maxAttempts: 1, baseDelay: 5 })
-      ).toThrowError('timeout is required');
-    });
-
-    it('validates maxAttempts is >= 1', () => {
-      expect(() =>
-        validateRuntimeOptions({
-          maxAttempts: 0,
-          baseDelay: 10,
-          timeout: 10,
-        })
-      ).toThrowError('maxAttempts must be greater than or equal to 1');
-    });
-
-    it('validates baseDelay is >= 1', () => {
-      expect(() =>
-        validateRuntimeOptions({
-          maxAttempts: 3,
-          baseDelay: 0,
-          timeout: 10,
-        })
-      ).toThrowError('baseDelay must be greater than or equal to 1');
-    });
-
-    it('validates timeout is >= 3', () => {
-      expect(() =>
-        validateRuntimeOptions({
-          maxAttempts: 3,
-          baseDelay: 10,
-          timeout: 2,
-        })
-      ).toThrowError('timeout must be greater than or equal to 3');
-    });
-  });
-
-  describe('when optional is true', () => {
-    it('accepts missing options', () => {
-      expect(() =>
-        validateRuntimeOptions({}, { optional: true })
-      ).not.toThrowError();
-      expect(() =>
-        validateRuntimeOptions({ maxAttempts: 1 }, { optional: true })
-      ).not.toThrowError();
-    });
-
-    it('still validates provided options', () => {
-      expect(() =>
-        validateRuntimeOptions(
-          {
-            maxAttempts: 0,
-          },
-          { optional: true }
-        )
-      ).toThrowError('maxAttempts must be greater than or equal to 1');
-
-      expect(() =>
-        validateRuntimeOptions(
-          {
-            baseDelay: 0,
-          },
-          { optional: true }
-        )
-      ).toThrowError('baseDelay must be greater than or equal to 1');
-
-      expect(() =>
-        validateRuntimeOptions(
-          {
-            timeout: 2,
-          },
-          { optional: true }
-        )
-      ).toThrowError('timeout must be greater than or equal to 3');
-    });
-  });
-
-  it('accepts valid options', () => {
-    expect(() =>
-      validateRuntimeOptions({
-        maxAttempts: 3,
-        baseDelay: 10,
-        timeout: 30,
-      })
-    ).not.toThrowError();
-  });
-});

package/__tests__/types/dsl-types.test-d.ts

@@ -1,103 +0,0 @@
-import { Flow } from '../../src/index.ts';
-import { describe, it, expectTypeOf } from 'vitest';
-
-describe('Flow Type System Tests', () => {
-  it('should properly type input argument for root steps', () => {
-    new Flow<{ id: number; email: string }>({
-      slug: 'test_flow',
-    }).step({ slug: 'root_a' }, (input) => {
-      expectTypeOf(input).toMatchTypeOf<{
-        run: { id: number; email: string };
-      }>();
-      return { result: 'test-result' };
-    });
-  });
-
-  it('should properly type input arguments for dependent steps', () => {
-    new Flow<{ id: number; email: string }>({
-      slug: 'test_flow',
-    })
-      .step({ slug: 'root_a' }, (input) => {
-        expectTypeOf(input).toMatchTypeOf<{
-          run: { id: number; email: string };
-        }>();
-        return { result: 'test-result' };
-      })
-      .step({ slug: 'step_a', dependsOn: ['root_a'] }, (input) => {
-        expectTypeOf(input).toMatchTypeOf<{
-          run: { id: number; email: string };
-          root_a: { result: string };
-        }>();
-        return { count: 42 };
-      })
-      .step(
-        { slug: 'final_step', dependsOn: ['root_a', 'step_a'] },
-        (input) => {
-          expectTypeOf(input).toMatchTypeOf<{
-            run: { id: number; email: string };
-            root_a: { result: string };
-            step_a: { count: number };
-          }>();
-          return { flag: true };
-        }
-      );
-  });
-
-  describe('Flow dependency validation', () => {
-    it('should catch non-existent steps at compile time', () => {
-      const testFlow = new Flow<string>({ slug: 'test_flow' }).step(
-        { slug: 'step1' },
-        () => 5
-      );
-
-      // Type assertion to verify compile-time error
-      type TestType = Parameters<typeof testFlow.step>[0]['dependsOn'];
-      // @ts-expect-error - should only allow 'step1' as a valid dependency
-      const invalidDeps: TestType = ['nonExistentStep'];
-    });
-
-    it('should not allow access to non-dependencies', () => {
-      new Flow<string>({ slug: 'test_flow' })
-        .step({ slug: 'step1' }, () => 1)
-        .step({ slug: 'step2' }, () => 2)
-        .step({ slug: 'step3', dependsOn: ['step1'] }, (payload) => {
-          expectTypeOf(payload).toMatchTypeOf<{
-            run: string;
-            step1: number;
-          }>();
-
-          // Verify that step2 is not accessible
-          expectTypeOf(payload).not.toHaveProperty('step2');
-
-          return payload.step1;
-        });
-    });
-  });
-
-  describe('Multi-level dependencies', () => {
-    it('should correctly type multi-level dependencies', () => {
-      new Flow<string>({ slug: 'test_flow' })
-        .step({ slug: 'first' }, (payload) => {
-          expectTypeOf(payload).toMatchTypeOf<{ run: string }>();
-          return 5;
-        })
-        .step({ slug: 'second', dependsOn: ['first'] }, (payload) => {
-          expectTypeOf(payload).toMatchTypeOf<{
-            run: string;
-            first: number;
-          }>();
-
-          return [payload.run] as string[];
-        })
-        .step({ slug: 'third', dependsOn: ['first', 'second'] }, (payload) => {
-          expectTypeOf(payload).toMatchTypeOf<{
-            run: string;
-            first: number;
-            second: string[];
-          }>();
-
-          return 15;
-        });
-    });
-  });
-});

package/__tests__/types/example-flow.test-d.ts

@@ -1,76 +0,0 @@
-import { it, expectTypeOf } from 'vitest';
-import { AnalyzeWebsite } from '../../src/example-flow.ts';
-
-const websiteStepDef = AnalyzeWebsite.getStepDefinition('website');
-const sentimentStepDef = AnalyzeWebsite.getStepDefinition('sentiment');
-const summaryStepDef = AnalyzeWebsite.getStepDefinition('summary');
-const saveToDbStepDef = AnalyzeWebsite.getStepDefinition('saveToDb');
-
-const run = { url: 'https://example.com' };
-const website = { content: 'holahola' };
-const summary = { aiSummary: 'holahola' };
-const sentiment = { score: 0.5 };
-
-it('should correctly handle AnalyzeWebsite flow steps with proper types', () => {
-  // Test website step handler type
-  expectTypeOf(websiteStepDef.handler).toBeFunction();
-  expectTypeOf(websiteStepDef.handler).parameters.toMatchTypeOf<
-    [{ run: { url: string } }]
-  >();
-  expectTypeOf(websiteStepDef.handler).returns.toMatchTypeOf<
-    Promise<{ content: string }> | { content: string }
-  >();
-
-  // Test sentiment step handler type
-  expectTypeOf(sentimentStepDef.handler).toBeFunction();
-  expectTypeOf(sentimentStepDef.handler).parameters.toMatchTypeOf<
-    [{ run: { url: string }; website: { content: string } }]
-  >();
-  expectTypeOf(sentimentStepDef.handler).returns.toMatchTypeOf<
-    Promise<{ score: number }> | { score: number }
-  >();
-
-  // Test summary step handler type
-  expectTypeOf(summaryStepDef.handler).toBeFunction();
-  expectTypeOf(summaryStepDef.handler).parameters.toMatchTypeOf<
-    [{ run: { url: string }; website: { content: string } }]
-  >();
-  expectTypeOf(summaryStepDef.handler).returns.toMatchTypeOf<
-    Promise<{ aiSummary: string }> | { aiSummary: string }
-  >();
-
-  // Test saveToDb step handler type
-  expectTypeOf(saveToDbStepDef.handler).toBeFunction();
-  expectTypeOf(saveToDbStepDef.handler).parameters.toMatchTypeOf<
-    [
-      {
-        run: { url: string };
-        sentiment: { score: number };
-        summary: { aiSummary: string };
-      }
-    ]
-  >();
-  expectTypeOf(saveToDbStepDef.handler).returns.toMatchTypeOf<
-    Promise<string> | string
-  >();
-});
-
-it('allows to call handlers with matching inputs', () => {
-  websiteStepDef.handler({ run });
-  sentimentStepDef.handler({ run, website });
-  summaryStepDef.handler({ run, website });
-  saveToDbStepDef.handler({ run, summary, sentiment });
-});
-it('does not allow to call with additional keys', () => {
-  // @ts-expect-error - no additional keys allowed
-  websiteStepDef.handler({ run, newKey: true });
-
-  // @ts-expect-error - no additional keys allowed
-  sentimentStepDef.handler({ run, website, newKey: true });
-
-  // @ts-expect-error - no additional keys allowed
-  summaryStepDef.handler({ run, website, newKey: true });
-
-  // @ts-expect-error - no additional keys allowed
-  saveToDbStepDef.handler({ run, summary, sentiment, newKey: true });
-});