Improving the author data type

[riazaia]

Context

You can, and probably should, skip this whole section if you already know how AO3 displays authors on a work. Skip to The Issue!

On the Archive Of Our Own, a work can be published by one or more users, under a default or non-default pseud, and be included in an anonymous collection or not. If a work is added to an anonymous collection, the work will display its author simply as "Anonymous" regardless of the number of creators.

When a user publishes a work using the default pseud (meaning, the value of the username and the pseud matches) the HTML on the page will be the following:

<h3 class="byline heading">
  <a rel="author" href="/users/<USERNAME>/pseuds/<PSEUD>">PSEUD</a>
</h3>

When the user uses a pseud other than the default:

<h3 class="byline heading">
  <a rel="author" href="/users/<USERNAME>/pseuds/<PSEUD>">PSEUD  (USERNAME)</a>
</h3>

For multiple creators, the links to the authors are separated by commas:

<h3 class="byline heading">
  <a rel="author" href="/users/<USERNAME>/pseuds/<PSEUD>">PSEUD</a>, <a rel="author" href="/users/<USERNAME>/pseuds/<PSEUD>">PSEUD (USERNAME)</a>
    </h3>

✨ FUN FACT: You can publish a work and set multiple of your own pseuds as co-creators.

When a work is part of an anononymous collection:

<h3 class="byline heading">
  Anonymous
</h3>

To account for these different situations, we decided on the following data shape:

export interface WorkSummary {
  // ...
  authors: "Anonymous" | Author[];
  // ...
}

where Author[] referrs to an array of the following:

export interface Author {
  username: string;
  pseud: string;
}

This works well and (we think) covers the situations mentioned above.

The Issue

However, a new challenger approaches! The Open Doors Project adds an extra quirk. Through OD, when an archive is imported an "archivist" account is created to host works. This account owns any imported works that existing AO3 users don't claim to their own accounts.

What this means in practice is that some works have a different format which looks like the following:

<h3 class="byline heading">
Author's Name [archived by <a rel="author" href="/users/X_archivist/pseuds/X_archivist">X_archivist</a>]
</h3>

I actually asked around (♥ to volunteers) and apparently a work with two creators would display as: Author1's Name [archived by x_archivist], Author2's Name [archived by x_archivist] if neither have claimed the work and Author1, Author2's Name [archived by x_archivist] if one has. And presumably that's the maximum number of imported co-creators that can be added this way.

Right now, the function that gets the author of a work looks at links to return the data, so the method is not broken per se, but it does present an issue of not being exactly right (since it sets the value of author the same that it would if X_archivist had created the work themselves, which bothers me personally).

The road so far..

Here's a summary of what we've discussed so far:

Priorities and considerations:

• create a solution that isn't a pain in the butt (it's probably a bad idea to make people check that username is not null before serving a URL, for example)
• consider: what would people want to do differently if something is archived by someone?
• what assumptions would we be breaking with our design if people didn't check that a username is null or that the work is a OD import (cause they aren't forced to)?
• consider: how can we minimize breaking the logic of other people's code

Assumptions

• The archivist account will not use a pseud other than the default
• A work can have a maximum of two non-AO3 user creators when being imported by OD (♥)
• Adding a work associated with an archivist account to an anonymous collection will change it's author to "Anonymous" (same behaviour as non-imports)
• This is a problem to solve and not an incredibly niche quirk that I'm fixated on for some reason

Proposals:

1. create a new property of type boolean for works imported by OD (e.g. open_doors: true).

   • should we make any additional changes besides adding this property? or would this be sufficient to inform anyone that cares that the attribution in the author property corresponds to an archivist account, and not the actual creator of the fanwork?

2. create a new property (e.g. original_author) of type Author to hold the data of the original creator of the work, such that a work will have the author propety set to the archivist account data and the original_author to one that looks like { username: null, pseud: "Author's Name" }

   • in order to do this we would need to change the type of the username property from string to string | null

3. Add a new type separate from Author for the archivist accounts:

export interface Author {
  username: string;
  pseud: string;
}

export interface ArchivedAuthor {
  username: null;
  pseud: string;
}

and then in the WorkSummary type:

authors: "Anonymous" | (Author | ArchivedAuthor)[];

4. Another possibility is to add another property such as:

export interface Author {
  username: string;
  pseud: string;
  archivist: boolean;
}

So people can check wether username corresponds to the true creator or the archivist account.

5. Instead of a true/false flag for wether the account is a regular user or an import archivist we can add a property referring to the original creator of the work, such as:

export interface Author {
  username: string;
  pseud: string;
  originalAuthor: string | null;
}

---

So yeah! That's the gist of it. Apologies for the length but I wanted everyone to have context so jumping into the discussion is easier, even if it is just to say that this doesn't seem like a huge issue as is works right now :D

[essential-randomness]

A few thoughts:

open_doors property

I think we should have open_doors: true as an easily-accessible property, as that will reduce the cognitive load people need when deciding whether a work is part of open doors. Sure, you could analyze the author array to see if it's an open door work, but:

1. you need to know that's a thing you can/should do
2. it makes for way more complex code when such a check is needed, and people would likely need to read the documentation to figure out how to implement it (and onlookers would also have a hard time understanding what's happening)

Author

(I'm assuming OD works where all the Authors have claimed the work are indistinguishable from regular works)

We could consider doing an Author type and an OpenDoorsArchivist type, maybe even having OpenDoorsArchivist extend Author.

export interface Author {
  username: string;
  pseud: string;
}

export interface OpenDoorsArchivist extends Author {
  originalAuthor: string;
}

This would make the type be:

authors: "Anonymous" | (Author | OpenDoorsArchivist)[];

if we change it this way, it becomes clearer that the username and pseud properties are of the Archivist, but allow people to still get the originalAuthor if they want.

We could also provide a utility function to distinguish:

const isArchivist = (author: Author | OpenDoorsArchivist) : author is OpenDoorsArchivist => {
 return "originalAuthor" in author;
}

This would help people discriminate between the types easily, even if they don't know the TS syntax for it.

Unrelated fun fact: changing the Author type

In typescript, you can remove properties from existing types, which means we could define originalAuthor based on the Author type without changing the type. So in your example, you could have:

export interface Author {
  username: string;
  pseud: string;
  // Note that we'd need to also omit originalAuthor not to make this recursive
  originalAuthor: Omit<Author, "username" | "originalAuthor">
} 

This would make Author be effectively:

export interface Author {
  username: string;
  pseud: string;
  originalAuthor: {
    pseud: string;
  }
} 

Omit documentation

[enigmalea]

Question about the practical implications ms. boba's suggestion:

When using the API in a typescript project, you're forced to check if the work is locked before you can do anything with the work already, would changing this force you to also always check if it's an openDoors project to work with the authors even if you don't care if it is?

If so will users find that annoying/cumbersome?

[essential-randomness]

TypeScript forces you to check before accessing properties only for the properties that aren't common to all the types a variable can have. So for a authors: "Anonymous" | (Author | OpenDoorsArchivist)[]; type, you will have to check if it's "Anonymous" before accessing the authors array, but you won't need to check whether a variable is Author or OpenDoorsArchivist unless you want to access the originalAuthor property (which is not in Author). We can "fix" this by changing Author to have the property but always set to null.

For openDoors, all the properties will be there regardless of the value of openDoors, so there's no need to check. Note that we could define types like this if we wanted to be perverse:

export interface Author {
  username: string;
  pseud: string;
}

export interface OpenDoorsArchivist extends Author {
  originalAuthor: string;
}

export interface Ao3WorkSummary {
  // omitting irrelevant fields
  openDoors: false;
  authors: "Anonymous" | Author[];
}

export interface OpenDoorWorkSummary extends Ao3WorkSummary {
  openDoors: true;
  authors: "Anonymous" | (Author | OpenDoorsArchivist)[];
}

// You can't have this union type with interfaces, so we need to use type here
type WorkSummary = Ao3WorkSummary | OpenDoorWorkSummary;

This would make it so that TS would be able to tell that if openDoors is false, then there's no OpenDoorsArchivist in the array.

Practically, I feel like this is pedantic overkill. We could try it though.

[essential-randomness]

Ok the syntax is a bit different, but behold the power of TypeScript

[essential-randomness]

Edit: MS BOBA IS WRONG HERE

Apparently we can indeed do this without the SharedWorkSummary interface, if that made you squeamish:

edit: nevermind, realized this doesn't exclude Author[] as a type for Authors in archived work.