feat: generate static schema (#1739)

Author: kuhe

.changeset/lazy-brooms-sip.md

@@ -0,0 +1,7 @@
+---
+"@smithy/smithy-client": minor
+"@smithy/types": minor
+"@smithy/core": minor
+---
+
+generation of static schema

packages/core/src/submodules/schema/TypeRegistry.ts

@@ -1,4 +1,4 @@
-import type { Schema as ISchema } from "@smithy/types";
+import type { Schema as ISchema, StaticErrorSchema } from "@smithy/types";
 
 import type { ErrorSchema } from "./schemas/ErrorSchema";
 
@@ -13,7 +13,7 @@ export class TypeRegistry {
   private constructor(
     public readonly namespace: string,
     private schemas: Map<string, ISchema> = new Map(),
-    private exceptions: Map<ErrorSchema, any> = new Map()
+    private exceptions: Map<ErrorSchema | StaticErrorSchema, any> = new Map()
   ) {}
 
   /**
@@ -53,16 +53,16 @@ export class TypeRegistry {
   /**
    * Associates an error schema with its constructor.
    */
-  public registerError(errorSchema: ErrorSchema, ctor: any) {
-    this.exceptions.set(errorSchema, ctor);
+  public registerError(es: ErrorSchema | StaticErrorSchema, ctor: any) {
+    this.exceptions.set(es, ctor);
   }
 
   /**
-   * @param errorSchema - query.
+   * @param es - query.
    * @returns Error constructor that extends the service's base exception.
    */
-  public getErrorCtor(errorSchema: ErrorSchema): any {
-    return this.exceptions.get(errorSchema);
+  public getErrorCtor(es: ErrorSchema | StaticErrorSchema): any {
+    return this.exceptions.get(es);
   }
 
   /**

packages/core/src/submodules/schema/middleware/schemaDeserializationMiddleware.ts

@@ -5,9 +5,11 @@ import type {
   HandlerExecutionContext,
   MetadataBearer,
   OperationSchema,
+  StaticOperationSchema,
 } from "@smithy/types";
 import { getSmithyContext } from "@smithy/util-middleware";
 
+import { hydrate, isStaticSchema } from "../schemas/NormalizedSchema";
 import type { PreviouslyResolved } from "./schema-middleware-types";
 
 /**
@@ -18,9 +20,13 @@ export const schemaDeserializationMiddleware =
   (next: DeserializeHandler<any, any>, context: HandlerExecutionContext) =>
   async (args: DeserializeHandlerArguments<any>) => {
     const { response } = await next(args);
-    const { operationSchema } = getSmithyContext(context) as {
-      operationSchema: OperationSchema;
+    let { operationSchema } = getSmithyContext(context) as {
+      operationSchema: OperationSchema | StaticOperationSchema;
     };
+    if (isStaticSchema(operationSchema)) {
+      operationSchema = hydrate(operationSchema);
+    }
+
     try {
       const parsed = await config.protocol.deserializeResponse(
         operationSchema,

packages/core/src/submodules/schema/middleware/schemaSerializationMiddleware.ts

@@ -6,9 +6,11 @@ import type {
   Provider,
   SerializeHandler,
   SerializeHandlerArguments,
+  StaticOperationSchema,
 } from "@smithy/types";
 import { getSmithyContext } from "@smithy/util-middleware";
 
+import { hydrate, isStaticSchema } from "../schemas/NormalizedSchema";
 import type { PreviouslyResolved } from "./schema-middleware-types";
 
 /**
@@ -18,9 +20,12 @@ export const schemaSerializationMiddleware =
   (config: PreviouslyResolved) =>
   (next: SerializeHandler<any, any>, context: HandlerExecutionContext) =>
   async (args: SerializeHandlerArguments<any>) => {
-    const { operationSchema } = getSmithyContext(context) as {
-      operationSchema: IOperationSchema;
+    let { operationSchema } = getSmithyContext(context) as {
+      operationSchema: IOperationSchema | StaticOperationSchema;
     };
+    if (isStaticSchema(operationSchema)) {
+      operationSchema = hydrate(operationSchema);
+    }
 
     const endpoint: Provider<Endpoint> =
       context.endpointV2?.url && config.urlParser

packages/core/src/submodules/schema/schemas/NormalizedSchema.spec.ts

@@ -8,6 +8,9 @@ import type {
   MapSchemaModifier,
   MemberSchema,
   NumericSchema,
+  StaticListSchema,
+  StaticMapSchema,
+  StaticStructureSchema,
   StreamingBlobSchema,
   StringSchema,
   StructureSchema,
@@ -313,4 +316,32 @@ describe(NormalizedSchema.name, () => {
       expect(ns.getEventStreamMember()).toEqual("");
     });
   });
+
+  describe("static schema", () => {
+    it("can normalize static schema indifferently to schema class objects", () => {
+      const [List, Map, Struct]: [StaticListSchema, StaticMapSchema, () => StaticStructureSchema] = [
+        [1, "ack", "List", { sparse: 1 }, 0],
+        [2, "ack", "Map", 0, 0, 1],
+        () => schema,
+      ];
+      const schema: StaticStructureSchema = [3, "ack", "Structure", {}, ["list", "map", "struct"], [List, Map, Struct]];
+
+      const ns = NormalizedSchema.of(schema);
+
+      expect(ns.isStructSchema()).toBe(true);
+      expect(ns.getMemberSchema("list").isListSchema()).toBe(true);
+      expect(ns.getMemberSchema("list").getMergedTraits().sparse).toBe(1);
+
+      expect(ns.getMemberSchema("map").isMapSchema()).toBe(true);
+      expect(ns.getMemberSchema("map").getKeySchema().isStringSchema()).toBe(true);
+      expect(ns.getMemberSchema("map").getValueSchema().isNumericSchema()).toBe(true);
+
+      expect(ns.getMemberSchema("struct").isStructSchema()).toBe(true);
+      expect(ns.getMemberSchema("struct").getMemberSchema("list").isListSchema()).toBe(true);
+      expect(ns.getMemberSchema("struct").getMemberSchema("list").getMergedTraits().sparse).toBe(1);
+      expect(ns.getMemberSchema("struct").getMemberSchema("map").isMapSchema()).toBe(true);
+      expect(ns.getMemberSchema("struct").getMemberSchema("map").getKeySchema().isStringSchema()).toBe(true);
+      expect(ns.getMemberSchema("struct").getMemberSchema("map").getValueSchema().isNumericSchema()).toBe(true);
+    });
+  });
 });

packages/core/src/submodules/schema/schemas/NormalizedSchema.ts

@@ -13,6 +13,14 @@ import type {
   SchemaRef,
   SchemaTraits,
   SchemaTraitsObject,
+  StaticErrorSchema,
+  StaticListSchema,
+  StaticMapSchema,
+  StaticOperationSchema,
+  StaticSchema,
+  StaticSchemaId,
+  StaticSimpleSchema,
+  StaticStructureSchema,
   StreamingBlobSchema,
   StringSchema,
   TimestampDefaultSchema,
@@ -22,11 +30,16 @@ import type {
 import type { IdempotencyTokenBitMask, TraitBitVector } from "@smithy/types/src/schema/traits";
 
 import { deref } from "../deref";
-import { ListSchema } from "./ListSchema";
-import { MapSchema } from "./MapSchema";
+import type { ErrorSchema } from "./ErrorSchema";
+import { error } from "./ErrorSchema";
+import { list, ListSchema } from "./ListSchema";
+import { map, MapSchema } from "./MapSchema";
+import type { OperationSchema } from "./OperationSchema";
+import { op } from "./OperationSchema";
 import { Schema } from "./Schema";
 import type { SimpleSchema } from "./SimpleSchema";
-import { StructureSchema } from "./StructureSchema";
+import { sim } from "./SimpleSchema";
+import { struct, StructureSchema } from "./StructureSchema";
 import { translateTraits } from "./translateTraits";
 
 /**
@@ -67,13 +80,15 @@ export class NormalizedSchema implements INormalizedSchema {
     let schema = ref;
     this._isMemberSchema = false;
 
-    while (Array.isArray(_ref)) {
+    while (isMemberSchema(_ref)) {
       traitStack.push(_ref[1]);
       _ref = _ref[0];
       schema = deref(_ref);
       this._isMemberSchema = true;
     }
 
+    if (isStaticSchema(schema)) schema = hydrate(schema);
+
     if (traitStack.length > 0) {
       this.memberTraits = {};
       for (let i = traitStack.length - 1; i >= 0; --i) {
@@ -96,7 +111,8 @@ export class NormalizedSchema implements INormalizedSchema {
     this.schema = deref(schema) as Exclude<ISchema, MemberSchema | INormalizedSchema>;
 
     if (this.schema && typeof this.schema === "object") {
-      this.traits = this.schema?.traits ?? {};
+      // excluded by the checked hydrate call above.
+      this.traits = (this.schema as Exclude<typeof this.schema, StaticSchema>)?.traits ?? {};
     } else {
       this.traits = 0;
     }
@@ -120,7 +136,7 @@ export class NormalizedSchema implements INormalizedSchema {
     if (sc instanceof NormalizedSchema) {
       return sc;
     }
-    if (Array.isArray(sc)) {
+    if (isMemberSchema(sc)) {
       const [ns, traits] = sc;
       if (ns instanceof NormalizedSchema) {
         Object.assign(ns.getMergedTraits(), translateTraits(traits));
@@ -331,7 +347,7 @@ export class NormalizedSchema implements INormalizedSchema {
     if (this.isStructSchema() && struct.memberNames.includes(memberName)) {
       const i = struct.memberNames.indexOf(memberName);
       const memberSchema = struct.memberList[i];
-      return member(Array.isArray(memberSchema) ? memberSchema : [memberSchema, 0], memberName);
+      return member(isMemberSchema(memberSchema) ? memberSchema : [memberSchema, 0], memberName);
     }
     if (this.isDocumentSchema()) {
       return member([15 satisfies DocumentSchema, 0], memberName);
@@ -409,3 +425,42 @@ function member(memberSchema: NormalizedSchema | [SchemaRef, SchemaTraits], memb
   const internalCtorAccess = NormalizedSchema as any;
   return new internalCtorAccess(memberSchema, memberName);
 }
+
+/**
+ * @internal
+ * @returns a class instance version of a static schema.
+ */
+export function hydrate(ss: StaticSimpleSchema): SimpleSchema;
+export function hydrate(ss: StaticListSchema): ListSchema;
+export function hydrate(ss: StaticMapSchema): MapSchema;
+export function hydrate(ss: StaticStructureSchema): StructureSchema;
+export function hydrate(ss: StaticErrorSchema): ErrorSchema;
+export function hydrate(ss: StaticOperationSchema): OperationSchema;
+export function hydrate(
+  ss: StaticSchema
+): SimpleSchema | ListSchema | MapSchema | StructureSchema | ErrorSchema | OperationSchema;
+export function hydrate(
+  ss: StaticSchema
+): SimpleSchema | ListSchema | MapSchema | StructureSchema | ErrorSchema | OperationSchema {
+  const [id, ...rest] = ss;
+  return (
+    {
+      [0 satisfies StaticSchemaId.Simple]: sim,
+      [1 satisfies StaticSchemaId.List]: list,
+      [2 satisfies StaticSchemaId.Map]: map,
+      [3 satisfies StaticSchemaId.Struct]: struct,
+      [-3 satisfies StaticSchemaId.Error]: error,
+      [9 satisfies StaticSchemaId.Operation]: op,
+    }[id] as Function
+  ).call(null, ...rest);
+}
+
+/**
+ * @internal
+ */
+const isMemberSchema = (sc: SchemaRef): sc is MemberSchema => Array.isArray(sc) && sc.length === 2;
+
+/**
+ * @internal
+ */
+export const isStaticSchema = (sc: SchemaRef): sc is StaticSchema => Array.isArray(sc) && sc.length >= 5;

packages/smithy-client/src/command.ts

@@ -17,6 +17,7 @@ import type {
   Pluggable,
   RequestHandler,
   SerdeContext,
+  StaticOperationSchema,
 } from "@smithy/types";
 import { SMITHY_CONTEXT_KEY } from "@smithy/types";
 
@@ -35,7 +36,7 @@ export abstract class Command<
 {
   public abstract input: Input;
   public readonly middlewareStack: IMiddlewareStack<Input, Output> = constructStack<Input, Output>();
-  public readonly schema?: OperationSchema;
+  public readonly schema?: OperationSchema | StaticOperationSchema;
 
   /**
    * Factory for Command ClassBuilder.
@@ -136,7 +137,7 @@ class ClassBuilder<
   private _outputFilterSensitiveLog: any = undefined;
   private _serializer: (input: I, context: SerdeContext | any) => Promise<IHttpRequest> = null as any;
   private _deserializer: (output: IHttpResponse, context: SerdeContext | any) => Promise<O> = null as any;
-  private _operationSchema?: OperationSchema;
+  private _operationSchema?: OperationSchema | StaticOperationSchema;
 
   /**
    * Optional init callback.
@@ -223,7 +224,7 @@ class ClassBuilder<
   /**
    * Sets input/output schema for the operation.
    */
-  public sc(operation: OperationSchema): ClassBuilder<I, O, C, SI, SO> {
+  public sc(operation: OperationSchema | StaticOperationSchema): ClassBuilder<I, O, C, SI, SO> {
     this._operationSchema = operation;
     this._smithyContext.operationSchema = operation;
     return this;
@@ -265,17 +266,19 @@ class ClassBuilder<
        * @internal
        */
       public resolveMiddleware(stack: IMiddlewareStack<any, any>, configuration: C, options: any): Handler<any, any> {
+        const op = closure._operationSchema;
+        const input = (op as StaticOperationSchema)?.[4] ?? (op as OperationSchema)?.input;
+        const output = (op as StaticOperationSchema)?.[5] ?? (op as OperationSchema)?.output;
+
         return this.resolveMiddlewareWithContext(stack, configuration, options, {
           CommandCtor: CommandRef,
           middlewareFn: closure._middlewareFn,
           clientName: closure._clientName,
           commandName: closure._commandName,
           inputFilterSensitiveLog:
-            closure._inputFilterSensitiveLog ??
-            (closure._operationSchema ? schemaLogFilter.bind(null, closure._operationSchema!.input) : (_) => _),
+            closure._inputFilterSensitiveLog ?? (op ? schemaLogFilter.bind(null, input) : (_) => _),
           outputFilterSensitiveLog:
-            closure._outputFilterSensitiveLog ??
-            (closure._operationSchema ? schemaLogFilter.bind(null, closure._operationSchema!.output) : (_) => _),
+            closure._outputFilterSensitiveLog ?? (op ? schemaLogFilter.bind(null, output) : (_) => _),
           smithyContext: closure._smithyContext,
           additionalContext: closure._additionalContext,
         });

packages/types/src/index.ts

@@ -23,6 +23,7 @@ export * from "./response";
 export * from "./retry";
 export * from "./schema/schema";
 export * from "./schema/sentinels";
+export * from "./schema/static-schemas";
 export * from "./serde";
 export * from "./shapes";
 export * from "./signature";

packages/types/src/schema/schema.ts

@@ -16,6 +16,7 @@ import type {
   TimestampEpochSecondsSchema,
   TimestampHttpDateSchema,
 } from "./sentinels";
+import type { StaticSchema } from "./static-schemas";
 import type { TraitBitVector } from "./traits";
 
 /**
@@ -31,6 +32,7 @@ export type Schema =
   | StructureSchema
   | MemberSchema
   | OperationSchema
+  | StaticSchema
   | NormalizedSchema;
 
 /**