@decaf-ts/as-graph 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +116 -0
- package/lib/cjs/dagster/DagsterGraphQLClient.cjs +738 -0
- package/lib/cjs/dagster/DagsterGraphQLClient.cjs.map +1 -0
- package/lib/cjs/dagster/index.cjs +1 -0
- package/lib/cjs/dagster/index.cjs.map +1 -1
- package/lib/cjs/nest/graph/GraphBackendHost.cjs +146 -0
- package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -0
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs +1 -0
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
- package/lib/cjs/nest/graph/index.cjs +1 -0
- package/lib/cjs/nest/graph/index.cjs.map +1 -1
- package/lib/cjs/nest/graph/main.cjs +97 -12
- package/lib/cjs/nest/graph/main.cjs.map +1 -1
- package/lib/esm/dagster/DagsterGraphQLClient.js +733 -0
- package/lib/esm/dagster/DagsterGraphQLClient.js.map +1 -0
- package/lib/esm/dagster/index.js +1 -0
- package/lib/esm/dagster/index.js.map +1 -1
- package/lib/esm/mastra/MastraCapabilities.js.map +1 -1
- package/lib/esm/nest/graph/GraphBackendHost.js +138 -0
- package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -0
- package/lib/esm/nest/graph/GraphExecutionModule.js +1 -0
- package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
- package/lib/esm/nest/graph/index.js +1 -0
- package/lib/esm/nest/graph/index.js.map +1 -1
- package/lib/esm/nest/graph/main.js +64 -12
- package/lib/esm/nest/graph/main.js.map +1 -1
- package/lib/types/dagster/DagsterGraphQLClient.d.cts +231 -0
- package/lib/types/dagster/DagsterGraphQLClient.d.mts +231 -0
- package/lib/types/dagster/index.d.cts +1 -0
- package/lib/types/dagster/index.d.mts +1 -0
- package/lib/types/mastra/MastraCapabilities.d.cts +0 -5
- package/lib/types/mastra/MastraCapabilities.d.mts +0 -5
- package/lib/types/nest/graph/GraphBackendHost.d.cts +100 -0
- package/lib/types/nest/graph/GraphBackendHost.d.mts +100 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.cts +12 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.mts +12 -0
- package/lib/types/nest/graph/index.d.cts +1 -0
- package/lib/types/nest/graph/index.d.mts +1 -0
- package/package.json +7 -1
package/README.md
CHANGED
|
@@ -620,11 +620,127 @@ import { KeycloakAuthHandler } from "@decaf-ts/integrations/nest";
|
|
|
620
620
|
export class AppModule {}
|
|
621
621
|
```
|
|
622
622
|
|
|
623
|
+
#### Running each backend + UI combination
|
|
624
|
+
|
|
625
|
+
The standalone host (`bin.as-graph-server`, `lib/cjs/nest/graph/main.cjs`) boots exactly one engine
|
|
626
|
+
variant, selected by `GRAPH_BACKEND_ENGINE`, and serves the C20 capability manifest
|
|
627
|
+
(`GET /graph/engines`) plus the per-engine workflow catalogue
|
|
628
|
+
(`GET /graph/engines/{engineId}/workflows`). The for-angular graph page talks to it over
|
|
629
|
+
`http://localhost:3000` (`GRAPH_BACKEND_URL`) and needs no code change when the variant changes — it
|
|
630
|
+
lists whatever the backend advertises and gates its actions on the served capabilities.
|
|
631
|
+
|
|
632
|
+
**Build first.** The scripts run the compiled entrypoint, so `npm run build` (or `build:prod`) must
|
|
633
|
+
have produced `lib/cjs/nest/graph/main.cjs`.
|
|
634
|
+
|
|
635
|
+
| Combination | Boot the backend | Run the UI | Backend port | Extra prerequisites |
|
|
636
|
+
| --- | --- | --- | --- | --- |
|
|
637
|
+
| standard (local engine) | `npm run start:backend` / `start:backend:local` | `npm run start` (for-angular, `:8110`) | `3000` | none — built-in reference interpreter |
|
|
638
|
+
| mastra | `npm run start:backend:mastra` | `npm run start` (for-angular, `:8110`) | `3000` | `@mastra/core` peer installed (`^1.77.0`) |
|
|
639
|
+
| dagster | `npm run start:backend:dagster` | `npm run start` (for-angular, `:8110`) | `3000` | a Dagster gateway + `DAGSTER_GRAPHQL_URL` (see below) |
|
|
640
|
+
|
|
641
|
+
From `for-angular`, `npm run start:dev` (local), `start:dev:mastra`, and `start:dev:dagster` boot
|
|
642
|
+
the backend and the UI together with `concurrently`.
|
|
643
|
+
|
|
644
|
+
| Variable | Default | Meaning |
|
|
645
|
+
| --- | --- | --- |
|
|
646
|
+
| `GRAPH_BACKEND_ENGINE` | `local` | `local` \| `mastra` \| `dagster`; an unknown value fails closed with `GRAPH_BACKEND_ENGINE_UNKNOWN` |
|
|
647
|
+
| `GRAPH_BACKEND_PORT` | `3000` | Backend HTTP port (the standalone binary also accepts the port as its first argument) |
|
|
648
|
+
| `DAGSTER_GRAPHQL_URL` | unset | Read-only Dagster client target. Without it the dagster backend still boots and serves the manifest, but the catalogue reports `NOT_SUPPORTED` (`501`) |
|
|
649
|
+
| `DAGSTER_EXECUTION_ENABLED` | `false` | Opt-in gate for launching/replaying existing Dagster runs |
|
|
650
|
+
| `GRAPH_BACKEND_URL` | `http://localhost:3000` | for-angular injection token for the backend base URL (a provider override, not an env var) |
|
|
651
|
+
|
|
652
|
+
The host binds to `127.0.0.1` and only admits `http://localhost`/`http://127.0.0.1` CORS origins
|
|
653
|
+
(development posture, SAA-595 F5).
|
|
654
|
+
|
|
655
|
+
##### Standard (local engine)
|
|
656
|
+
|
|
657
|
+
No backing service. Build the backend, boot it, and run the UI in a second terminal:
|
|
658
|
+
|
|
659
|
+
```bash
|
|
660
|
+
# as-graph
|
|
661
|
+
npm run build && npm run start:backend # http://127.0.0.1:3000 (engine: local)
|
|
662
|
+
# for-angular
|
|
663
|
+
npm run start # http://localhost:8110
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
Verify the backend advertises the local engine:
|
|
667
|
+
|
|
668
|
+
```bash
|
|
669
|
+
curl -s http://127.0.0.1:3000/graph/engines # .defaultEngineId == "local"
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
Open the graph route (`http://localhost:8110/graph`); the workflow table lists the workflows
|
|
673
|
+
persisted in the backend's local engine store.
|
|
674
|
+
|
|
675
|
+
##### Mastra
|
|
676
|
+
|
|
677
|
+
In-process; the only prerequisite is the `@mastra/core` peer dependency (pinned `^1.77.0`),
|
|
678
|
+
resolved by `npm install` in `as-graph`. The host lazily builds a real `@mastra/core` runtime.
|
|
679
|
+
|
|
680
|
+
```bash
|
|
681
|
+
npm run start:backend:mastra # engine: mastra, still on :3000
|
|
682
|
+
```
|
|
683
|
+
|
|
684
|
+
The Mastra catalogue lists workflows already compiled/executed in the process (its
|
|
685
|
+
`workflowList`/`workflowLookup` capability), so `GET /graph/engines/mastra/workflows` returns `[]`
|
|
686
|
+
until a workflow is run. The manifest advertises the mastra engine and its per-feature verdicts.
|
|
687
|
+
|
|
688
|
+
##### Dagster
|
|
689
|
+
|
|
690
|
+
Dagster is Python-side and has no JavaScript runtime, so the backend lists/executes through a
|
|
691
|
+
host-injected `DagsterClient` built from `DAGSTER_GRAPHQL_URL`. Provision the pinned gateway fixture
|
|
692
|
+
(Docker; Dagster `1.13.25`) with the integration harness:
|
|
693
|
+
|
|
694
|
+
```bash
|
|
695
|
+
# as-graph: boot + seed the pinned gateway and persist its GraphQL URL
|
|
696
|
+
npm run prepare-it-tests # publishes the gateway at http://127.0.0.1:3300/graphql
|
|
697
|
+
DAGSTER_GRAPHQL_URL=http://127.0.0.1:3300/graphql npm run start:backend:dagster
|
|
698
|
+
npm run teardown-it-tests # when done
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
Without `DAGSTER_GRAPHQL_URL` the dagster host still boots and serves the manifest; its catalogue
|
|
702
|
+
answers `501` (`NOT_SUPPORTED`). To run against an already-running Dagster, set
|
|
703
|
+
`DAGSTER_GRAPHQL_URL` yourself and skip `prepare-it-tests`.
|
|
704
|
+
|
|
705
|
+
> **Environment note (CI sandbox):** inside a container (`/.dockerenv`), the fixture joins the
|
|
706
|
+
> runner's network namespace and binds `127.0.0.1:3000`, which collides with the graph backend's
|
|
707
|
+
> default port. On a normal host the fixture is published at `127.0.0.1:3300`, so there is no
|
|
708
|
+
> collision. Because the for-angular UI is wired to `http://localhost:3000`, run the Dagster gateway
|
|
709
|
+
> on a host (or another namespace) and keep the graph backend on `3000` when exercising the UI +
|
|
710
|
+
> dagster combination.
|
|
711
|
+
|
|
712
|
+
##### Verifying the UI lists a backend's scenarios
|
|
713
|
+
|
|
714
|
+
1. `GET /graph/engines` returns the manifest with `defaultEngineId` equal to the booted variant.
|
|
715
|
+
2. `GET /graph/engines/{engineId}/workflows` returns that engine's catalogue (`200`), or `501` when
|
|
716
|
+
the engine declares no listing support (dagster without a client).
|
|
717
|
+
3. In the UI the workflow table shows the catalogue rows and gates create/run/save per the manifest
|
|
718
|
+
verdicts; switching variants requires no UI code change.
|
|
719
|
+
|
|
720
|
+
##### Running each variant's test suite
|
|
721
|
+
|
|
722
|
+
| Variant | Command |
|
|
723
|
+
| --- | --- |
|
|
724
|
+
| standard (local) | `npm run test:integration:standard` |
|
|
725
|
+
| mastra | `npm run test:integration:mastra` |
|
|
726
|
+
| dagster | `npm run prepare-it-tests` then `npm run test:integration:dagster` (or `npm run teardown-it-tests` after) |
|
|
727
|
+
| backend host boot (all variants + standalone binary) | `npm run test:integration:backend` |
|
|
728
|
+
|
|
729
|
+
The dagster suite needs the gateway fixture (`prepare-it-tests`) and Docker; it skips honestly when
|
|
730
|
+
no gateway is prepared. The standalone-binary boot test needs the `lib/cjs` build and skips when it
|
|
731
|
+
is absent.
|
|
732
|
+
|
|
623
733
|
#### Scripts
|
|
624
734
|
|
|
625
735
|
| Script | Purpose |
|
|
626
736
|
| --- | --- |
|
|
627
737
|
| `npm run build` / `build:prod` | Compile ESM + CJS + types |
|
|
738
|
+
| `npm run start:backend` / `start:backend:local` | Boot the standalone host with the built-in local engine (`:3000`) |
|
|
739
|
+
| `npm run start:backend:mastra` | Boot the standalone host with the Mastra engine (`GRAPH_BACKEND_ENGINE=mastra`) |
|
|
740
|
+
| `npm run start:backend:dagster` | Boot the standalone host with the Dagster engine (`GRAPH_BACKEND_ENGINE=dagster`) |
|
|
741
|
+
| `npm run test:integration:standard` / `:mastra` / `:dagster` | Run one engine variant's integration suite |
|
|
742
|
+
| `npm run test:integration:backend` | Run the host-boot integration suite (all variants + standalone binary) |
|
|
743
|
+
| `npm run prepare-it-tests` / `teardown-it-tests` | Provision / stop the pinned Dagster gateway fixture |
|
|
628
744
|
| `npm run test:unit` / `test:integration` / `test:e2e` | Run the Jest unit / integration / e2e suites |
|
|
629
745
|
| `npm run test:all` | Run the entire Jest suite (unit, integration, e2e) |
|
|
630
746
|
| `npm run test:dist` | Re-run the full suite against the compiled `lib` and `dist` outputs |
|