Support for Partial and ReadOnly/Visibility types

[arabold]

I'm creating a REST interface and want to re-use a model in a different place but change all of its properties to being optional and read-only. For example, having a Partial<Foo> data type would allow to making all properties optional for use in a PATCH HTTP request. Making all properties of a model read-only (setting their visibility to "read") would also be helpful to have more flexibility in API design without redefining the model.

What I'm looking for are two data types (and possible variations):

1. Partial<Model> should make all properties of Model optional. In some cases a PartialDeep<Model> might be useful as well.
2. ReadOnly<Model>, Visibility<Model, "read"> and/or a DefaultVisibility<Model, "read"> to overwrite the visibility of all properties

Is it possible to build a custom TypeSpec library to add these features or would this need to be added in the core?

[arabold]

I keep answering my own questions 😆

After digging through the source code a bit, I was able to create a custom @withPartial and @withSetVisibility decorator. It was much simpler than I anticipated.

In case anyone is interested in the code:

import {
  $visibility,
  type DecoratorContext,
  type Model,
  type ModelProperty,
  validateDecoratorTarget,
} from '@typespec/compiler';

function updateModelPropertiesInPlace(
  model: Model,
  callback: (key: string, prop: ModelProperty) => ModelProperty,
) {
  for (const [key, prop] of model.properties) {
    const updatedProp = callback(key, prop);
    model.properties.set(key, updatedProp);
  }
}

export const $withPartial = (
  context: DecoratorContext,
  target: Model,
): void => {
  if (!validateDecoratorTarget(context, target, '@withPartial', 'Model')) {
    return;
  }
  updateModelPropertiesInPlace(target, (key, prop) => {
    if (prop.optional) return prop;
    return { ...prop, optional: true };
  });
};

export const $withSetVisibility = (
  context: DecoratorContext,
  target: Model,
  ...visibilities: string[]
): void => {
  if (
    !validateDecoratorTarget(context, target, '@withSetVisibility', 'Model')
  ) {
    return;
  }
  updateModelPropertiesInPlace(target, (key, prop) => {
    return {
      ...prop,
      decorators: [
        ...prop.decorators.filter((d) => d.decorator !== $visibility),
        {
          decorator: $visibility,
          args: visibilities.map((visibility) => ({
            value: context.program.checker.createLiteralType(visibility),
            jsValue: visibility,
          })),
        },
      ],
    };
  });
  for (const [key, prop] of target.properties) {
    $visibility(context, prop, ...visibilities);
  }
};

and the decorators.tsp:

extern dec withPartial(target: Model);
extern dec withSetVisibility(target: Model, ...visibilities: valueof string[]);

[bterlson]

Glad you were able to figure it out. We should definitely document this pattern better, although it is a bit of a stopgap in that, eventually our type system should be able to express these kinds of patterns using a mapped types like syntax.

Note that eventually we will be automatically producing JSON merge patch schemas when it's an input to an operation with a content type of "application/merge-patch+json". So hopefully this just goes away.

Can you say more about when you need to toggle visibility, e.g. overwrite all properties to have read visibility? The entire visibility feature is designed specifically to allow you to use a single model across multiple contexts (one model for all lifecycle operations, instead of N models). If we're missing a scenario there I want to understand it better!

[arabold]

Our example might be a bit convoluted but here's how I'm using Partial<Model> and ReadOnly<Model>:

Assume I have an Author and a Book model:

model Author {
  @key
  @visibility("read")
  authorId: string;
  name: string;
  birthDate: plainDate;
  @visibility("read")
  books: Book[];
}

model Book {
  @key
  @visibility("read")
  bookId: string;
  title: string;
  year: integer;
  @visibily("read")
  authors: Author[];
}

In my API I want to be able to create a new Book and link an existing Author to it. But if we make the authors field writeable ("create", "update") then the API client will need to provide all mandatory fields. Hence the introduction of Partial, so all fields are becoming optional. This could look like this:

model Book {
  @key
  @visibility("read")
  bookId: string;
  title: string;
-  @visibily("read")
-  authors: Author[];
+  authors: AuthorRef[];
}

model AuthorRef {
  authorId: string;
  ...Partial<OmitProperties<Author, "authorId">>;
}

This already works quite well! Now I can query books and get all author information (i.e. GET /books/123?includeAuthors=true). When creating a new book I only need to provide the authorId (as I defined it as mandatory field above) but nothing else:

// POST /books
{
  "title": "The Great Gatsby",
  "authors": [
    { "authorId": "123" }
  ]
}

However, this API might still be a bit confusing for the client as you can provide more fields for an author during the creation of a new book, even though it wouldn't make much sense. So, can we fix this and only allow authorId when creating a book but still return all other fields when querying? This is where ReadOnly<Model> comes into play:

model AuthorRef {
  authorId: string;
-  ...Partial<OmitProperties<Author, "authorId">>;
+  ...Partial<ReadOnly<OmitProperties<Author, "authorId">>>;
}

Now I can use the same Book model both for reading and writing.