Function ObjectAttribute

  • ObjectAttribute<
        T extends default,
        const S extends ObjectSchema,
        P extends ObjectAttributeOptions<S>,
    >(
        props: P,
    ): (
        _value: undefined,
        context: AttributeDecoratorContext<T, InferObjectSchema<S>, P>,
    ) => void

  • A decorator for marking class fields as structured object attributes within the context of a single-table design entity.

    Objects are stored as native DynamoDB Map types and validated at runtime against the provided schema. The TypeScript type is inferred from the schema using InferObjectSchema.

    Can be set to nullable via decorator props.

    Supported field types within the schema:

    • "string", "number", "boolean" — primitives
    • "enum" — string literal unions, validated at runtime via z.enum()
    • "object" — nested objects (arbitrarily deep)
    • "array" — lists of any field type

    All field types support nullable: true to allow null values.

    Type Parameters

    • T extends default

      The class type that the decorator is applied to

    • const S extends ObjectSchema

      The ObjectSchema type used for validation and type inference

    • P extends ObjectAttributeOptions<S>

      The decorator options type

    Parameters

    Returns (
        _value: undefined,
        context: AttributeDecoratorContext<T, InferObjectSchema<S>, P>,
    ) => void

    A class field decorator function

    Usage example:

    const addressSchema = {
      street: { type: "string" },
      city: { type: "string" },
      zip: { type: "number", nullable: true },
      category: { type: "enum", values: ["home", "work", "other"] },
      geo: {
        type: "object",
        fields: {
          lat: { type: "number" },
          lng: { type: "number" },
          accuracy: { type: "enum", values: ["precise", "approximate"] }
        }
      }
    } as const satisfies ObjectSchema;

    class MyEntity extends MyTable {
      @ObjectAttribute({ alias: 'Address', schema: addressSchema })
      public address: InferObjectSchema<typeof addressSchema>;

      @ObjectAttribute({ alias: 'Meta', schema: metaSchema, nullable: true })
      public meta?: InferObjectSchema<typeof metaSchema>;
    }

    // TypeScript infers:
    // address.category → "home" | "work" | "other"
    // address.geo.accuracy → "precise" | "approximate"

    Object attributes support filtering in queries using dot-path notation for nested fields and the ContainsFilter | $contains operator for List membership checks.

    await MyEntity.query("123", {
      filter: { "address.city": "Springfield" }
    });

    await MyEntity.query("123", {
      filter: { "address.tags": { $contains: "home" } }
    });

Settings

Member Visibility