Support v0.1.0-rc.14 of the NDC spec

changelog.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2.0.0
+Breaking change: support for the [v0.1.0-rc.14 of NDC Spec](https://github.com/hasura/ndc-spec/compare/v0.1.0-rc.13...v0.1.0-rc.14).
+
+- Function name formatting is now standard JavaScript `camelCase`. NDC types used for wire-transmission match the spec (snake_cased).
+- Added [nested field selections](https://github.com/hasura/ndc-spec/pull/70) (`Field.fields`)
+- Capabilities now only specifies [a single supported version](https://github.com/hasura/ndc-spec/pull/82) (`CapabilitiesResponse.version`)
+- `Expression.where` [renamed](https://github.com/hasura/ndc-spec/pull/87) to `Expression.predicate`
+- `PathElement.predicate` is now [optional](https://github.com/hasura/ndc-spec/pull/87)
+- Added [Predicate types](https://github.com/hasura/ndc-spec/blob/main/rfcs/0002-boolean-expression-types.md) (new `predicate` Type.type)
+- Added [mutation capability](https://github.com/hasura/ndc-spec/pull/80)
+- Comparison operators
+- [Changes to explain](https://github.com/hasura/ndc-spec/pull/85):
+  - `Connector.explain` renamed to `Connector.queryExplain` and endpoint moved from `/explain` to `/query/explain`.
+  - `Connector.mutationExplain` added with endpoint `/mutation/explain`.
+  - `explain` capability moved to `query.explain`. `mutation.explain` capability added.
+- `ComparisonOperatorDefinition` now has `equal` and `in` as [two standard definitions](https://github.com/hasura/ndc-spec/pull/79/files) and custom operators can be defined. The equality operator is no longer required to be defined and must be explicitly defined.
+
 ## 1.2.8
 - Add new `ConnectorError` types:
   - `UnprocessableContent`: The request could not be handled because, while the request was well-formed, it was not semantically correct. For example, a value for a custom scalar type was provided, but with an incorrect type

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasura/ndc-sdk-typescript",
-  "version": "1.2.8",
+  "version": "2.0.0",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

src/configuration_server.ts → src/configuration-server.ts

@@ -17,11 +17,13 @@ const errorResponses = {
   400: ErrorResponseSchema,
   403: ErrorResponseSchema,
   409: ErrorResponseSchema,
+  422: ErrorResponseSchema,
   500: ErrorResponseSchema,
   501: ErrorResponseSchema,
+  502: ErrorResponseSchema,
 };
 
-export async function start_configuration_server<
+export async function startConfigurationServer<
   RawConfiguration,
   Configuration,
   State
@@ -41,32 +43,32 @@ export async function start_configuration_server<
     }
   );
 
-  const raw_configuration_schema = connector.get_raw_configuration_schema();
+  const rawConfigurationSchema = connector.getRawConfigurationSchema();
 
   server.get(
     "/",
     {
       schema: {
         response: {
-          200: raw_configuration_schema,
+          200: rawConfigurationSchema,
           ...errorResponses,
         },
       },
     },
     async function get_schema(
       _request: FastifyRequest
     ): Promise<RawConfiguration> {
-      return connector.make_empty_configuration();
+      return connector.makeEmptyConfiguration();
     }
   );
 
   server.post(
     "/",
     {
       schema: {
-        body: raw_configuration_schema,
+        body: rawConfigurationSchema,
         response: {
-          200: raw_configuration_schema,
+          200: rawConfigurationSchema,
           ...errorResponses,
         },
       },
@@ -76,7 +78,7 @@ export async function start_configuration_server<
         Body: RawConfiguration;
       }>
     ): Promise<RawConfiguration> => {
-      return connector.update_configuration(
+      return connector.updateConfiguration(
         // type assertion required because Configuration is a generic parameter
         request.body as RawConfiguration
       );
@@ -93,14 +95,14 @@ export async function start_configuration_server<
         },
       },
     },
-    async (): Promise<JSONSchemaObject> => raw_configuration_schema
+    async (): Promise<JSONSchemaObject> => rawConfigurationSchema
   );
 
   server.post(
     "/validate",
     {
       schema: {
-        body: raw_configuration_schema,
+        body: rawConfigurationSchema,
         response: {
           200: ValidateResponseSchema,
           ...errorResponses,
@@ -110,12 +112,12 @@ export async function start_configuration_server<
     async (
       request: FastifyRequest<{ Body: RawConfiguration }>
     ): Promise<ValidateResponse> => {
-      const resolvedConfiguration = await connector.validate_raw_configuration(
+      const resolvedConfiguration = await connector.validateRawConfiguration(
         // type assertion required because Configuration is a generic parameter
         request.body as RawConfiguration
       );
-      const schema = await connector.get_schema(resolvedConfiguration);
-      const capabilities = connector.get_capabilities(resolvedConfiguration);
+      const schema = await connector.getSchema(resolvedConfiguration);
+      const capabilities = connector.getCapabilities(resolvedConfiguration);
 
       return {
         schema,

src/connector.ts

@@ -14,7 +14,7 @@ export interface Connector<RawConfiguration, Configuration, State> {
   /**
    * Return jsonschema for the raw configuration for this connector
    */
-  get_raw_configuration_schema(): JSONSchemaObject;
+  getRawConfigurationSchema(): JSONSchemaObject;
 
   /**
    * Return an empty raw configuration, to be manually filled in by the user to allow connection to the data source.
@@ -28,22 +28,22 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * }
    * ```
    */
-  make_empty_configuration(): RawConfiguration;
+  makeEmptyConfiguration(): RawConfiguration;
   /**
    * Take a raw configuration, update it where appropriate by connecting to the underlying data source, and otherwise return it as-is
    * For example, if our configuration includes a list of tables, we may want to fetch an updated list from the data source.
    * This is also used to "hidrate" an "empty" configuration where a user has provided connection details and little else.
    * @param rawConfiguration a base raw configuration
    */
-  update_configuration(
+  updateConfiguration(
     rawConfiguration: RawConfiguration
   ): Promise<RawConfiguration>;
   /**
    * Validate the raw configuration provided by the user,
    * returning a configuration error or a validated [`Connector::Configuration`].
    * @param configuration
    */
-  validate_raw_configuration(
+  validateRawConfiguration(
     rawConfiguration: RawConfiguration
   ): Promise<Configuration>;
 
@@ -58,7 +58,7 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * @param configuration
    * @param metrics
    */
-  try_init_state(
+  tryInitState(
     configuration: Configuration,
     metrics: unknown
   ): Promise<State>;
@@ -74,7 +74,7 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * @param configuration
    * @param state
    */
-  fetch_metrics(configuration: Configuration, state: State): Promise<undefined>;
+  fetchMetrics(configuration: Configuration, state: State): Promise<undefined>;
   /**
    * Check the health of the connector.
    *
@@ -85,7 +85,7 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * @param configuration
    * @param state
    */
-  health_check(configuration: Configuration, state: State): Promise<undefined>;
+  healthCheck(configuration: Configuration, state: State): Promise<undefined>;
 
   /**
    * Get the connector's capabilities.
@@ -96,7 +96,7 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * This function should be syncronous
    * @param configuration
    */
-  get_capabilities(configuration: Configuration): CapabilitiesResponse;
+  getCapabilities(configuration: Configuration): CapabilitiesResponse;
 
   /**
    * Get the connector's schema.
@@ -105,7 +105,7 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * from the NDC specification.
    * @param configuration
    */
-  get_schema(configuration: Configuration): Promise<SchemaResponse>;
+  getSchema(configuration: Configuration): Promise<SchemaResponse>;
 
   /**
    * Explain a query by creating an execution plan
@@ -116,12 +116,27 @@ export interface Connector<RawConfiguration, Configuration, State> {
    * @param state
    * @param request
    */
-  explain(
+  queryExplain(
     configuration: Configuration,
     state: State,
     request: QueryRequest
   ): Promise<ExplainResponse>;
 
+  /**
+   * Explain a mutation by creating an execution plan
+   *
+   * This function implements the [explain endpoint](https://hasura.github.io/ndc-spec/specification/explain.html)
+   * from the NDC specification.
+   * @param configuration
+   * @param state
+   * @param request
+   */
+  mutationExplain(
+    configuration: Configuration,
+    state: State,
+    request: MutationRequest
+  ): Promise<ExplainResponse>;
+
   /**
    * Execute a mutation
    *

src/index.ts

@@ -1,14 +1,14 @@
 import { Connector } from "./connector";
 import { Command, Option, InvalidOptionArgumentError } from "commander";
-import { ServerOptions, start_server } from "./server";
+import { ServerOptions, startServer } from "./server";
 import {
   ConfigurationServerOptions,
-  start_configuration_server,
-} from "./configuration_server";
+  startConfigurationServer,
+} from "./configuration-server";
 
 export * from "./error";
 export * from "./schema";
-export { Connector, ServerOptions, ConfigurationServerOptions, start_configuration_server, start_server };
+export { Connector, ServerOptions, ConfigurationServerOptions, startConfigurationServer, startServer };
 
 /**
  * Starts the connector.
@@ -22,13 +22,13 @@ export function start<RawConfiguration, Configuration, State>(
 ) {
   const program = new Command();
 
-  program.addCommand(get_serve_command(connector));
-  program.addCommand(get_serve_configuration_command(connector));
+  program.addCommand(getServeCommand(connector));
+  program.addCommand(getServeConfigurationCommand(connector));
 
   program.parseAsync(process.argv).catch(console.error);
 }
 
-export function get_serve_command<RawConfiguration, Configuration, State>(
+export function getServeCommand<RawConfiguration, Configuration, State>(
   connector?: Connector<RawConfiguration, Configuration, State>
 ) {
   const command = new Command("serve")
@@ -53,13 +53,13 @@ export function get_serve_command<RawConfiguration, Configuration, State>(
 
   if (connector) {
     command.action(async (options: ServerOptions) => {
-      await start_server(connector, options);
+      await startServer(connector, options);
     })
   }
   return command;
 }
 
-export function get_serve_configuration_command<
+export function getServeConfigurationCommand<
   RawConfiguration,
   Configuration,
   State
@@ -76,7 +76,7 @@ export function get_serve_configuration_command<
 
   if (connector) {
     serveCommand.action(async (options: ConfigurationServerOptions) => {
-      await start_configuration_server(connector, options);
+      await startConfigurationServer(connector, options);
     });
   }
 

src/schema/index.ts

@@ -1,23 +1,23 @@
 import { JSONSchemaObject } from "@json-schema-tools/meta-schema";
 import schema from "./schema.generated.json";
 
-function schema_for_type(type_name: string): JSONSchemaObject {
+function schemaForType(type_name: string): JSONSchemaObject {
   return {
     $schema: schema.$schema,
     $ref: `#/definitions/${type_name}`,
     definitions: schema.definitions
   }
 }
 
-const CapabilitiesResponseSchema = schema_for_type("CapabilitiesResponse");
-const SchemaResponseSchema = schema_for_type("SchemaResponse");
-const QueryRequestSchema = schema_for_type("QueryRequest");
-const QueryResponseSchema = schema_for_type("QueryResponse");
-const ExplainResponseSchema = schema_for_type("ExplainResponse");
-const MutationRequestSchema = schema_for_type("MutationRequest");
-const MutationResponseSchema = schema_for_type("MutationResponse");
-const ErrorResponseSchema = schema_for_type("ErrorResponse");
-const ValidateResponseSchema = schema_for_type("ValidateResponse");
+const CapabilitiesResponseSchema = schemaForType("CapabilitiesResponse");
+const SchemaResponseSchema = schemaForType("SchemaResponse");
+const QueryRequestSchema = schemaForType("QueryRequest");
+const QueryResponseSchema = schemaForType("QueryResponse");
+const ExplainResponseSchema = schemaForType("ExplainResponse");
+const MutationRequestSchema = schemaForType("MutationRequest");
+const MutationResponseSchema = schemaForType("MutationResponse");
+const ErrorResponseSchema = schemaForType("ErrorResponse");
+const ValidateResponseSchema = schemaForType("ValidateResponse");
 
 export * from "./schema.generated";
 export {