Winglang with generics and opaque types (feat DynamoDB)

[skyrpex]

DynamoDB is a NoSQL database which allows you to work with JSON documents. Every database item has a primary key, and any number of attributes. The JSON documents must follow the following format:

await dynamodb.putItem({
  // Some string attributes.
  id: { S: "user_123" },
  name: { S: "Cristian" },
  // A list of strings.
  colors: { SS: ["red", "blue"] },
  // A number. It can hold up to 38 digits so in JS it may need the use of bigint.
  age: { N: "34" },
  // A boolean.
  isAdult: { B: "true" },
  // A date timestamp.
  createdAt: { N: "601858800000" },
  // A string date.
  deletedAt: { S: "1989-01-28T00:00:00.000Z" },
});

As you can see, the attribute type is defined by the key of the object and the values are mostly represented as strings. Retrieving items from DynamoDB will use the same format. This means that, in order to work with these items, some data conversions may be necessary, such as:

const item = await dynamodb.getItem({ id: { S: "user_123" } });

const age = Number(item.age.N); // or BigInt(item.age.N)

const isAdult = item.isAdult.B === "true";

const createdAt = new Date(Number(item.createdAt.N));

const deletedAt = new Date(item.deletedAt.S);

These conversions can be tedious and error-prone, but can be alleviated with the help of a type system such as TypeScript.

// We can define a type for the DynamoDB item.
declare const dynamodb: DynamoDB<{
  item: {
    id: string;
    name: string;
    colors: Color[];
    age: StringEncoded<bigint>;
    isAdult: "true" | "false";
    createdAt: StringEncoded<Timestamp>;
    deletedAt: StringEncoded<Date>;
  };
}>;

// And some helper functions to convert the DynamoDB item to our type.
declare function bigIntFromString(s: StringEncoded<bigint>): bigint;
declare function booleanFromString(s: "true" | "false"): boolean;
declare function dateFromTimestamp(s: StringEncoded<Timestamp>): Date;
declare function dateFromString(s: StringEncoded<Date>): Date;

const item = await dynamodb.getItem({ id: { S: "user_123" } });

// It's now trivial to work with the item.
const age = bigIntFromString(item.age.N);
const isAdult = booleanFromString(item.isAdult.B);
const createdAt = dateFromTimestamp(item.createdAt.N);
const deletedAt = dateFromString(item.deletedAt.S);

Writing items can also take advantage of the type system:

await dynamodb.putItem({
  // This will fail because "not a number" is not a StringEncoded<bigint>
  age: { N: "not a number" },
  //        ^^^^^^^^^^^^^^ Error: Type string is not assignable to StringEncoded<bigint>.

  // Whereas this will work.
  age: { N: stringEncode(34n) },
});

Type safety can further be improved by using opaque types. Let's say we're working with different type of IDs:

// By using opaque types, the type system will prevent us from mixing them up.
type UserId = OpaqueType<string, { readonly t: unique symbol }>;
type BlogId = OpaqueType<string, { readonly t: unique symbol }>;

declare async function createBlogEntry(
  userId: UserId,
  blogId: BlogId,
  blogEntry: string
): Promise<void>;

// ...
declare const userId: UserId;
declare const blogId: BlogId;
createBlogEntry(blogId, userId, "hello world!");
//              ^^^^^^ Error: Type 'BlogId' is not assignable to type 'UserId'.

Conclusion

Winglang would benefit a lot from a type system similar to TypeScript: a structural type system with type inference, generics, and opaque types. This would allow for a more robust and type-safe codebase, and would make it easier to work with external APIs such as DynamoDB.

Some native types would be very welcome:

• JsonSerializable
• JsonEncoded<T>
• jsonEncode<T extends JsonSerializable>(data: T): JsonEncoded<T>
• Stringifiable
• StringEncoded<T>
• stringEncode<T extends Stringifiable>(data: T): StringEncoded<T>
• opaque<T>