Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update TS SDK version to v6.1.0, use Hasura-forked ts-node-dev #43

Merged
merged 5 commits into from
Aug 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,12 @@ This changelog documents the changes between release versions.
## [Unreleased]
Changes to be included in the next upcoming release

## [1.7.0] - 2024-08-27
- Added `documentationPage` to the connector metadata to enable the `ddn` CLI to suggest documentation to users ([#41](https://github.com/hasura/ndc-nodejs-lambda/pull/41))
- Added multi-platform support to the `hasura/ndc-nodejs-lambda` docker image. It now supports both linux/amd64 and linux/arm64 platforms ([#42](https://github.com/hasura/ndc-nodejs-lambda/pull/42))
- Updated the NDC TypeScript SDK to v6.1.0 ([#43](https://github.com/hasura/ndc-nodejs-lambda/pull/43))
- Support for [querying nested collections](https://hasura.github.io/ndc-spec/specification/queries/filtering.html#nested-collections) inside an EXISTS expression in a predicate
- Use a [Hasura-forked version](https://github.com/hasura/ts-node-dev) of [ts-node-dev](https://github.com/wclr/ts-node-dev) (used for hot-reloading in watch mode) to upgrade deprecated dependencies ([#43](https://github.com/hasura/ndc-nodejs-lambda/pull/43))

## [1.6.0] - 2024-08-08
- Updated the NDC TypeScript SDK to v6.0.0 ([#39](https://github.com/hasura/ndc-nodejs-lambda/pull/39))
Expand Down
44 changes: 22 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,17 @@ The Node.js Lambda connector allows you to expose TypeScript functions as NDC fu
> To see it in use in a wider Hasura DDN project, and to understand the underlying DDN concepts, please check out the [Hasura DDN Getting Started Guide](https://hasura.io/docs/3.0/getting-started/overview/).
> The Node.js Lambda connector is used in the [business logic](https://hasura.io/docs/3.0/getting-started/build/add-business-logic?db=TypeScript) part of that tutorial.

First, ensure you have Node.js v20+ installed and an existing Hasura DDN project created (see the [Hasura DDN Getting Started Guide](https://hasura.io/docs/3.0/getting-started/overview/)). Then, initialize the connector into that project on an unused port of your choosing:
First, ensure you have Node.js v20+ installed and an existing Hasura DDN project created (see the [Hasura DDN Getting Started Guide](https://hasura.io/docs/3.0/getting-started/overview/)). Then, initialize the connector into that project:

```bash
ddn connector init my_ts --subgraph my_subgraph/subgraph.yaml --hub-connector hasura/nodejs --configure-port 8085
ddn connector init -i
```

This will generate the necessary files into the `my_subgraph/connector/my_ts` directory. This creates a `functions.ts` file in which you will write your functions, and a `package.json` with the `ndc-lambda-sdk` installed into it.

To add a `DataConnectorLink` to link the connector into the wider Hasura DDN project, run:
* Select `hasura/nodejs` from the list of connectors
* Name it something descriptive. For this example, we'll call it `my_ts`
* Choose a port (press enter to accept the default recommended by the CLI).

```bash
ddn connector-link add my_ts \
--subgraph my_subgraph/subgraph.yaml \
--configure-host http://local.hasura.dev:8085 \
--target-env-file my_subgraph/.env.my_subgraph.local
```
This will generate the necessary files into the `my_subgraph/connector/my_ts` directory. This creates a `functions.ts` file in which you will write your functions, and a `package.json` with the `ndc-lambda-sdk` installed into it.

Restore all the npm packages required to run the connector by running inside the connector's directory:

Expand All @@ -34,35 +29,40 @@ npm install
To run the connector with the required environment variables applied, you can run the following command:

```bash
npx dotenv -e .env.local -- npm run watch
ddn connector setenv --connector connector.yaml -- npm run watch
```

This starts the connector in watch mode, which watches for code changes and restarts the connector when they are detected. `npm run start` can be used instead to just start the connector without watching for changes. Both `start` and `watch` are defined in the `package.json`'s scripts section and use the `ndc-lambda-sdk` to host your `functions.ts` file.

Once you have written your functions, and while the connector is running, you can update that `DataConnectorLink` and add all the new functions to your subgraph by running:
Once you have written your functions, use the following to generate the related metadata that will link together any functions in this functions.ts file and your API:

```bash
ddn connector introspect my_ts
```

Then you can generate all the necessary `hml` files with the Commands that expose your functions in the API by running the following:

```bash
ddn connector-link update my_ts \
--subgraph my_subgraph/subgraph.yaml \
--env-file my_subgraph/.env.my_subgraph.local \
--add-all-resources
ddn connector-link add-resources my_ts
```

To make a local build of your supergraph you can run:

```bash
ddn supergraph build local \
--output-dir engine \
--subgraph-env-file my_subgraph:my_subgraph/.env.my_subgraph.local
ddn supergraph build local
```

You can then run that build locally for testing by starting the engine and other connectors in the DDN project using Docker Compose:

```bash
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose up --build --watch
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose --env-file .env up --build --watch
```

You can view and query that local instance using the Hasura Graphiql Explorer by navigating to `https://console.hasura.io/local/graphql?url=http://localhost:3000`.
You can view and query that local instance using the Hasura Graphiql Explorer by running:

```bash
ddn console --local
```

### Functions
Any functions exported from `functions.ts` are made available as NDC functions/procedures to use in your Hasura metadata and expose as GraphQL fields in queries or mutation.
Expand Down
Loading