feat(core/schema): add docblocks

Author: kuhe

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

@@ -1,9 +1,10 @@
-import { describe, test as it, expect } from "vitest";
-import { TypeRegistry } from "./TypeRegistry";
+import { describe, expect, test as it } from "vitest";
+
+import { error } from "./schemas/ErrorSchema";
 import { list } from "./schemas/ListSchema";
 import { map } from "./schemas/MapSchema";
 import { struct } from "./schemas/StructureSchema";
-import { error } from "./schemas/ErrorSchema";
+import { TypeRegistry } from "./TypeRegistry";
 
 describe(TypeRegistry.name, () => {
   const [List, Map, Struct] = [list("ack", "List", { sparse: 1 }, 0), map("ack", "Map", 0, 0, 1), () => schema];

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

@@ -28,7 +28,8 @@ export class TypeRegistry {
   }
 
   /**
-   * The active type registry's namespace is used.
+   * Adds the given schema to a type registry with the same namespace.
+   *
    * @param shapeId - to be registered.
    * @param schema - to be registered.
    */
@@ -50,6 +51,19 @@ export class TypeRegistry {
     return this.schemas.get(id)!;
   }
 
+  /**
+   * The smithy-typescript code generator generates a synthetic (i.e. unmodeled) base exception,
+   * because generated SDKs before the introduction of schemas have the notion of a ServiceBaseException, which
+   * is unique per service/model.
+   *
+   * This is generated under a unique prefix that is combined with the service namespace, and this
+   * method is used to retrieve it.
+   *
+   * The base exception synthetic schema is used when an error is returned by a service, but we cannot
+   * determine what existing schema to use to deserialize it.
+   *
+   * @returns the synthetic base exception of the service namespace associated with this registry instance.
+   */
   public getBaseException(): ErrorSchema | undefined {
     for (const [id, schema] of this.schemas.entries()) {
       if (id.startsWith("smithyts.client.synthetic.") && id.endsWith("ServiceException")) {
@@ -59,10 +73,17 @@ export class TypeRegistry {
     return undefined;
   }
 
-  public find(seeker: (schema: ISchema) => boolean) {
-    return [...this.schemas.values()].find(seeker);
+  /**
+   * @param predicate - criterion.
+   * @returns a schema in this registry matching the predicate.
+   */
+  public find(predicate: (schema: ISchema) => boolean) {
+    return [...this.schemas.values()].find(predicate);
   }
 
+  /**
+   * Unloads the current TypeRegistry.
+   */
   public destroy() {
     TypeRegistry.registries.delete(this.namespace);
     this.schemas.clear();

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

@@ -3,6 +3,14 @@ import type { SchemaRef, SchemaTraits } from "@smithy/types";
 import { TypeRegistry } from "../TypeRegistry";
 import { StructureSchema } from "./StructureSchema";
 
+/**
+ * A schema for a structure shape having the error trait. These represent enumerated operation errors.
+ * Because Smithy-TS SDKs use classes for exceptions, whereas plain objects are used for all other data,
+ * and have an existing notion of a XYZServiceBaseException, the ErrorSchema differs from a StructureSchema
+ * by additionally holding the class reference for the corresponding ServiceException class.
+ *
+ * @public
+ */
 export class ErrorSchema extends StructureSchema {
   public constructor(
     public name: string,
@@ -18,6 +26,18 @@ export class ErrorSchema extends StructureSchema {
   }
 }
 
+/**
+ * Factory for ErrorSchema, to reduce codegen output and register the schema.
+ *
+ * @internal
+ *
+ * @param namespace - shapeId namespace.
+ * @param name - shapeId name.
+ * @param traits - shape level serde traits.
+ * @param memberNames - list of member names.
+ * @param memberList - list of schemaRef corresponding to each
+ * @param ctor - class reference for the existing Error extending class.
+ */
 export function error(
   namespace: string,
   name: string,

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

@@ -3,6 +3,12 @@ import type { ListSchema as IListSchema, SchemaRef, SchemaTraits } from "@smithy
 import { TypeRegistry } from "../TypeRegistry";
 import { Schema } from "./Schema";
 
+/**
+ * A schema with a single member schema.
+ * The deprecated Set type may be represented as a list.
+ *
+ * @public
+ */
 export class ListSchema extends Schema implements IListSchema {
   public constructor(
     public name: string,
@@ -13,6 +19,11 @@ export class ListSchema extends Schema implements IListSchema {
   }
 }
 
+/**
+ * Factory for ListSchema.
+ *
+ * @internal
+ */
 export function list(namespace: string, name: string, traits: SchemaTraits = {}, valueSchema: SchemaRef): ListSchema {
   const schema = new ListSchema(
     namespace + "#" + name,

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

@@ -3,6 +3,10 @@ import type { MapSchema as IMapSchema, SchemaRef, SchemaTraits } from "@smithy/t
 import { TypeRegistry } from "../TypeRegistry";
 import { Schema } from "./Schema";
 
+/**
+ * A schema with a key schema and value schema.
+ * @public
+ */
 export class MapSchema extends Schema implements IMapSchema {
   public constructor(
     public name: string,
@@ -17,6 +21,10 @@ export class MapSchema extends Schema implements IMapSchema {
   }
 }
 
+/**
+ * Factory for MapSchema.
+ * @internal
+ */
 export function map(
   namespace: string,
   name: string,

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

@@ -1,12 +1,12 @@
+import { MemberSchema } from "@smithy/types";
 import { describe, expect, test as it } from "vitest";
 
 import { list } from "./ListSchema";
 import { map } from "./MapSchema";
 import { NormalizedSchema } from "./NormalizedSchema";
-import { struct } from "./StructureSchema";
-import { sim } from "./SimpleSchema";
-import { MemberSchema } from "@smithy/types";
 import { SCHEMA } from "./sentinels";
+import { sim } from "./SimpleSchema";
+import { struct } from "./StructureSchema";
 
 describe(NormalizedSchema.name, () => {
   const [List, Map, Struct] = [list("ack", "List", { sparse: 1 }, 0), map("ack", "Map", 0, 0, 1), () => schema];

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

@@ -15,20 +15,26 @@ import { SimpleSchema } from "./SimpleSchema";
 import { StructureSchema } from "./StructureSchema";
 
 /**
- * Wraps SchemaRef values for easier handling.
- * @internal
+ * Wraps both class instances, numeric sentinel values, and member schema pairs.
+ * Presents a consistent interface for interacting with polymorphic schema representations.
+ *
+ * @public
  */
 export class NormalizedSchema implements INormalizedSchema {
-  public readonly name: string;
-  public readonly traits: SchemaTraits;
+  private readonly name: string;
+  private readonly traits: SchemaTraits;
 
   private _isMemberSchema: boolean;
-  private schema: Exclude<ISchema, MemberSchema>;
+  private schema: Exclude<ISchema, MemberSchema | INormalizedSchema>;
   private memberTraits: SchemaTraits;
   private normalizedTraits?: SchemaTraitsObject;
 
+  /**
+   * @param ref - a polymorphic SchemaRef to be dereferenced/normalized.
+   * @param memberName - optional memberName if this NormalizedSchema should be considered a member schema.
+   */
   public constructor(
-    public readonly ref: SchemaRef,
+    private readonly ref: SchemaRef,
     private memberName?: string
   ) {
     const traitStack = [] as SchemaTraits[];
@@ -65,7 +71,7 @@ export class NormalizedSchema implements INormalizedSchema {
       return;
     }
 
-    this.schema = deref(schema) as Exclude<ISchema, MemberSchema>;
+    this.schema = deref(schema) as Exclude<ISchema, MemberSchema | INormalizedSchema>;
 
     if (this.schema && typeof this.schema === "object") {
       this.traits = this.schema?.traits ?? {};
@@ -83,6 +89,9 @@ export class NormalizedSchema implements INormalizedSchema {
     }
   }
 
+  /**
+   * Static constructor that attempts to avoid wrapping a NormalizedSchema within another.
+   */
   public static of(ref: SchemaRef, memberName?: string): NormalizedSchema {
     if (ref instanceof NormalizedSchema) {
       return ref;
@@ -124,7 +133,13 @@ export class NormalizedSchema implements INormalizedSchema {
     return traits;
   }
 
-  private static memberFrom(memberSchema: [SchemaRef, SchemaTraits], memberName: string): NormalizedSchema {
+  /**
+   * Creates a normalized member schema from the given schema and member name.
+   */
+  private static memberFrom(
+    memberSchema: NormalizedSchema | [SchemaRef, SchemaTraits],
+    memberName: string
+  ): NormalizedSchema {
     if (memberSchema instanceof NormalizedSchema) {
       memberSchema.memberName = memberName;
       memberSchema._isMemberSchema = true;
@@ -133,16 +148,23 @@ export class NormalizedSchema implements INormalizedSchema {
     return new NormalizedSchema(memberSchema, memberName);
   }
 
-  public getSchema(): Exclude<ISchema, MemberSchema> {
+  /**
+   * @returns the underlying non-normalized schema.
+   */
+  public getSchema(): Exclude<ISchema, MemberSchema | INormalizedSchema> {
     if (this.schema instanceof NormalizedSchema) {
       return (this.schema = this.schema.getSchema());
     }
     if (this.schema instanceof SimpleSchema) {
-      return deref(this.schema.schemaRef) as Exclude<ISchema, MemberSchema>;
+      return deref(this.schema.schemaRef) as Exclude<ISchema, MemberSchema | INormalizedSchema>;
     }
-    return deref(this.schema) as Exclude<ISchema, MemberSchema>;
+    return deref(this.schema) as Exclude<ISchema, MemberSchema | INormalizedSchema>;
   }
 
+  /**
+   * @param withNamespace - qualifies the name.
+   * @returns e.g. `MyShape` or `com.namespace#MyShape`.
+   */
   public getName(withNamespace = false): string | undefined {
     if (!withNamespace) {
       if (this.name && this.name.includes("#")) {
@@ -153,6 +175,10 @@ export class NormalizedSchema implements INormalizedSchema {
     return this.name || undefined;
   }
 
+  /**
+   * @returns the member name if the schema is a member schema.
+   * @throws Error when the schema isn't a member schema.
+   */
   public getMemberName(): string {
     if (!this.isMemberSchema()) {
       throw new Error(`@smithy/core/schema - cannot get member name on non-member schema: ${this.getName(true)}`);
@@ -168,6 +194,9 @@ export class NormalizedSchema implements INormalizedSchema {
     return this.getSchema() === ("unit" as const);
   }
 
+  /**
+   * boolean methods on this class help control flow in shape serialization and deserialization.
+   */
   public isListSchema(): boolean {
     const inner = this.getSchema();
     if (typeof inner === "number") {
@@ -230,6 +259,10 @@ export class NormalizedSchema implements INormalizedSchema {
     return this.getSchema() === SCHEMA.STREAMING_BLOB;
   }
 
+  /**
+   * @returns own traits merged with member traits, where member traits of the same trait key take priority.
+   * This method is cached.
+   */
   public getMergedTraits(): SchemaTraitsObject {
     if (this.normalizedTraits) {
       return this.normalizedTraits;
@@ -241,14 +274,26 @@ export class NormalizedSchema implements INormalizedSchema {
     return this.normalizedTraits;
   }
 
+  /**
+   * @returns only the member traits. If the schema is not a member, this returns empty.
+   */
   public getMemberTraits(): SchemaTraitsObject {
     return NormalizedSchema.translateTraits(this.memberTraits);
   }
 
+  /**
+   * @returns only the traits inherent to the shape or member target shape if this schema is a member.
+   * If there are any member traits they are excluded.
+   */
   public getOwnTraits(): SchemaTraitsObject {
     return NormalizedSchema.translateTraits(this.traits);
   }
 
+  /**
+   * @returns the map's key's schema. Returns a dummy Document schema if this schema is a Document.
+   *
+   * @throws Error if the schema is not a Map or Document.
+   */
   public getKeySchema(): NormalizedSchema {
     if (this.isDocumentSchema()) {
       return NormalizedSchema.memberFrom([SCHEMA.DOCUMENT, 0], "key");
@@ -263,6 +308,12 @@ export class NormalizedSchema implements INormalizedSchema {
     return NormalizedSchema.memberFrom([(schema as MapSchema).keySchema, 0], "key");
   }
 
+  /**
+   * @returns the schema of the map's value or list's member.
+   * Returns a dummy Document schema if this schema is a Document.
+   *
+   * @throws Error if the schema is not a Map, List, nor Document.
+   */
   public getValueSchema(): NormalizedSchema {
     const schema = this.getSchema();
 
@@ -295,12 +346,21 @@ export class NormalizedSchema implements INormalizedSchema {
     throw new Error(`@smithy/core/schema - the schema ${this.getName(true)} does not have a value member.`);
   }
 
-  public getMemberSchema(member: string): NormalizedSchema | undefined {
+  /**
+   * @returns the NormalizedSchema for the given member name. The returned instance will return true for `isMemberSchema()`
+   * and will have the member name given.
+   * @param member - which member to retrieve and wrap.
+   *
+   * @throws Error if member does not exist or the schema is neither a document nor structure.
+   * Note that errors are assumed to be structures and unions are considered structures for these purposes.
+   */
+  public getMemberSchema(member: string): NormalizedSchema {
     if (this.isStructSchema()) {
       const struct = this.getSchema() as StructureSchema;
       if (!(member in struct.members)) {
-        // indicates the member is not recognized.
-        return undefined;
+        throw new Error(
+          `@smithy/core/schema - the schema ${this.getName(true)} does not have a member with name=${member}.`
+        );
       }
       return NormalizedSchema.memberFrom(struct.members[member], member);
     }
@@ -310,6 +370,9 @@ export class NormalizedSchema implements INormalizedSchema {
     throw new Error(`@smithy/core/schema - the schema ${this.getName(true)} does not have members.`);
   }
 
+  /**
+   * @returns a map of member names to member schemas (normalized).
+   */
   public getMemberSchemas(): Record<string, NormalizedSchema> {
     const { schema } = this;
     const struct = schema as StructureSchema;
@@ -326,6 +389,9 @@ export class NormalizedSchema implements INormalizedSchema {
     return {};
   }
 
+  /**
+   * @returns a last-resort human-readable name for the schema if it has no other identifiers.
+   */
   private getSchemaName(): string {
     const schema = this.getSchema();
     if (typeof schema === "number") {

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

@@ -3,6 +3,12 @@ import type { OperationSchema as IOperationSchema, SchemaRef, SchemaTraits } fro
 import { TypeRegistry } from "../TypeRegistry";
 import { Schema } from "./Schema";
 
+/**
+ * This is used as a reference container for the input/output pair of schema, and for trait
+ * detection on the operation that may affect client protocol logic.
+ *
+ * @public
+ */
 export class OperationSchema extends Schema implements IOperationSchema {
   public constructor(
     public name: string,
@@ -14,6 +20,10 @@ export class OperationSchema extends Schema implements IOperationSchema {
   }
 }
 
+/**
+ * Factory for OperationSchema.
+ * @internal
+ */
 export function op(
   namespace: string,
   name: string,