Thanks to a comprehensive test suite and browser automation testing, over 170 issues have been closed on Github with almost no regressions, and the new features added from 1.0 to the current 1.11 are always non-intrusive and backward-compatible.

This is much thanks to the simple API, which works on the deconstruct principle that you only expose what you need. So when you call superForm (basically the only API you need on the client), the initial call is very simple:

// Only deconstruct what you need
const { form } = superForm(data.form);

And as you move along and introduce additional features like client-side validation, error handling, loading spinners, you just keep deconstructing what you need, together with configuration as an optional parameter:

const { form, errors, enhance, delayed } = superForm(data.form, {
  resetForm: true
});

This encapsulates the whole form behavior within a single function call, making things simple to both understand and expand upon.

So in general, all is well with version 1, but there's one thing that comes up now and then, touching on a problem that, when you enter the rabbit hole, goes quite deep.

This text is written in two parts, the first one is the background to the problem, and the second is how to solve it.

Part 1: The already-solved problem

Looking at the numerous validation libraries out there, it's obvious that validation is quite a popular problem to tackle, having led to a friendly competition where the focus seems to be mostly on performance and bundle size. That is certainly a too simple view in most cases, so I apologize, but I say it because the problem itself - validation - has already been solved.

Most validation libraries don't add any brand-new features. Instead, they bring higher speed, smaller size and a different syntax, where at least the first two can be useful, unless it's the evil premature optimization.

More could be said about this, but even if we accept that people fill the ecosystem with similar libraries and consider that a good thing for everyone, there's a deeper issue at hand.

Schema validation vs. Form validation

A frequent question for Superforms is "Does it support validation library X?" If it did, this writing wouldn't exist, so naturally the answer is no, it only supports Zod. This can be disappointing, given that there are smaller and faster libraries out there. So am I a Zod fanboy, made a big oversight, or is there another reason for not supporting any other library?

I do think Zod is great, but I did plenty of research before settling on it because there's a big difference between a schema validation library, which just handles validating data, and a form validation library like Superforms, which must handle numerous other aspects of the validation process. What others? Let's take a look at a rather overlooked one, type safety.

Schema type safety

The idea with Superforms is that the validation schema encapsulates a single form, so the schema can be a single source of truth for the form, including its data, which type can be inferred from the schema. This means that if you have a schema like:

const schema = z.object({
  name: z.string().min(2)
  email: z.string().email()
})

The inferred type of the data is:

type Schema = z.infer<typeof schema>;

// Resulting type:
{
  name: string;
  email: string;
}

Note that the types here are string, not string | undefined, since the fields aren't optional in the schema. So when you're using this data, the fields must be set to a string. You can't just use an empty object, any operation on the supposed string data will then fail.

Some validation libraries solve this with default values, but adding that to every field is rather tedious:

const schema = z.object({
  name: z.string().min(2).default('')
  email: z.string().email().default('')
  score: z.number().default(0)
  // ...and 10+ more fields
})

Others don't care, as they just focus on the data validation. In either case, it puts an additional burden on the library consumer - supply default values, or your data won't be type-safe.

Having an extra data structure with default values for every schema is not only tedious but redundant since the information is already there. Looking at the schema, you know that name and email are strings. But how to access this information programmatically? This leads us to the problem at hand: You must be able to introspect the schema, to avoid burdening the user.

Introspection

Introspection is the ability to examine the type or properties of an object at runtime. A related concept is reflection, which goes a step further and also allows manipulation of these properties.

This is essential for form validation because if it would be possible to introspect on the above schema, we could loop through the properties and see that name is a string, and then set a default value, an empty string in this case, that makes the data type-safe. No burden on the user, no additional data structure.

You may have figured out the problem already - which of the popular validation libraries support introspection?

Assuming that it must be a documented and quite stable feature, the answer is, as of November 2023, not many except Zod do.

Some libraries like Ajv are using JSON Schema, which is a formidable attempt at a validation standard, self-reflecting since it's just JSON. Compared to the fluent syntax of a validation library with IDE autocompletion, it can appear quite verbose though. Compare this Zod schema:

const schema = z.object({
  name: z.string().min(2)
  email: z.string().email()
})

To the equivalent JSON Schema:

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 2 },
    "email": { "type": "string", "format": "email" }
  },
  "required": [ "name", "email" ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Because of that, libraries like Typebox have been created to simplify JSON Schema generation. But wouldn't it be nice to use only your favorite library, instead of having to jump through the hoops of

Typebox → Ajv → Validate data → Get default values from JSON Schema → Type-safe form data

Zod makes this quite easy since you can access the schema as objects:

function defaultValue(zodType: ZodTypeAny) {
  switch(zodType._def.typeName) {
    case 'ZodString': return '';
    case 'ZodNumber': return 0;
    case 'ZodObject': {
      const zodObject = zodType as AnyZodObject
      for (const [key, value] of Object.entries(zodObject.shape)) {
        // Call defaultValue recursively to assign each property
      }
    }
    // ... and so on
  }
}

(typeName is used instead of instanceof to avoid prototype mismatch, which can happen if packages use different versions of Zod. Kudos to the author Colin McDonnell for acknowledging this.)

Now, for smaller systems, a few default values or extra data structures for the schemas could be manageable. But it gets more problematic when we look at another aspect, one where introspection turns into a dire need.

Constraint validation in the browser

HTML5 introduced constraint validation, attributes on the form elements that improve validation by giving feedback in the browser, even if Javascript is disabled.

They can be easily added to any input field:

<input name="name" required="true" minlength="2" />

However, given that we have a schema with the purpose of defining validation constraints, applying these manually on every field is also quite redundant. Mapping the schema to browser validation constraints would be quite preferable, since there are plenty of attributes to deal with. Min/max values for numbers, the essential required attribute, pattern matching, etc.

To do this, you need to be able to extract constraints based on every schema field. The required attribute is an especially good example since it requires knowledge about whether the field is optional or nullable.

With Superforms introspecting the Zod schema, you'll get this for free and can use the constraints just by spreading its variable on an input field:

<script lang="ts">
  export const data;
  const { form, constraints } = superForm(data.form);
</script>

Name: <input name="name" bind:value={$form.name} {...$constraints.name} />

(Thanks Svelte for this cool feature!)

This is very convenient and useful, but puts some demands on the introspection capabilities of the validation library. Implementing that requires some planning beforehand, or a larger rewrite otherwise, so it may not be a high priority. But by not supporting introspection, the library is doing its users a considerable disservice.

The library vendor lock-in

Every validation library has its DSL (domain-specific language) for the domain-specific task of validating data. This DSL is also known as the schema syntax. The syntax itself is a part of the programming language and is not easily accessible at runtime, so we must rely on the library to expose the schema metadata through its API. If we cannot access and transform it into something else, suddenly your library of choice may force you to manually handle default values and constraints separately, even though you see everything you need to automate it, every time you look at the schema.

This is essentially the same as being committed and locked into a specific vendor, that refuses to open up a way of accessing its data or integrating its features.

That's why I'm strongly advocating that the popular validation libraries, and all future ones, must add introspection capabilities, even if it's more enjoyable to work on shaving microseconds off the benchmark comparison instead.

Of course, due to the nature of Open Source Software, it's not possible to demand this of the library maintainers. Most of us do it in our spare time, because it's enjoyable and interesting, like a hobby. But here it is in writing, at least, and if the point of publishing a library is about doing something good for others (otherwise, please don't publish it), I hope that adding a decidedly important feature is desirable as well as tinkering with the fun parts.

Part 2: Solving the problem

To summarize part 1, the problem is as follows:

1. We want to use a favorite validation library together with Superforms.

2. We want the data to be inferred from its schema, for type-safety and DX.

3. We don't want to deal with default values and constraints by hand - they should be derived from the schema at runtime.

And of course, without feeling a bit demanding on the open-source contributors that work for free, we want all this even if our favorite validation library doesn't have any introspection capabilities! In which case we're prepared to make things a bit more redundant, to enjoy the speed, size and/or syntax of the chosen library.

This may look daunting, but here's the upside of OSS - there may be a lot of libraries out there, some similar to each other, but thanks to the sheer amount, there will also be libraries that solve a specific problem for almost anything.

Problem 1 - Use any validation library

As mentioned, the "simple problem" of pure validation has been solved already. We want to take some data as input and get validation errors as output. As this is what validation is about at its core, it should be possible to unify most libraries to solve our first problem.

And it comes as no surprise that this has been made already, by a library called TypeSchema. It has adapters currently for 14 validation libraries, unifying the validation process in a common API. If Superforms was only about error reporting, we'd be done by now. We're not, but this is still a tremendous help.

Problem 2 - Type inference

What about problem 2, type inference for the form data? This is even simpler. TypeSchema handles it very well, as can be seen by its coverage table. The rest, like transforming the inferred data type to an error type, is handled by Typescript and its mapped types.

Problem 3 - Introspection

But we also need introspection. Is there a unified solution even for that?

Here's where JSON Schema comes in as a true savior. If we can generate a JSON Schema for each library and its schemas, we have a standard to follow, which can be converted to default values and constraints with ease. This is how standards should be used, behind the scenes, so their verbose style won't get in the way of users. Many thanks to the JSON Schema creators for taking the time to painstakingly define - and thereby in detail solve - the problem of data validation.

And guess what, converting schemas back and forth has also been solved already! At least for a few libraries. Zod schemas can be converted to JSON Schema with a library not surprisingly called zod-to-json-schema. Other libraries like Ajv are already using JSON Schema, so the schema can just be lifted from there. If needed, we could use another nice piece of software like json-schema-to-ts to infer the types directly from the JSON Schema.

For the others, the best would be to raise the issue at the respective library repo, so a JSON Schema exporter can be built in, or at least introspection capabilities so a converter can be made. Until that, coding the JSON Schema by hand is a tedious option, so as a middle way, a data structure with default values could be converted to a JSON Schema with to-json-schema. There won't be any constraints with such a solution, but that may not always be a requirement anyway.

The v2 API

With all the problems solved, we can now formulate an API for Superforms version 2 based on the capabilities of each validation library. The function used to validate data in Superforms is called superValidate. It takes 1-3 parameters:

• schema: The validation schema.

• [Optional] data: Data that should be validated, can be from a DB or FormData in an HTTP request. If missing, use default values.

• [Optional] options: Extra options.

Case 1: Library has introspection

const form = await superValidate(schema, data)

This is the best case, where everything is handled conveniently behind the scenes by mapping the schema metadata to JSON Schema.

Case 2: No introspection, but JSON Schema is available.

const form = await superValidate(schema, data, { jsonSchema })

If a JSON Schema can be created by some other means, passing it as an extra option will ensure that default values and constraints are generated properly.

Case 3: No introspection, no JSON Schema.

const form = await superValidate(schema, data, { defaults })

If a JSON Schema isn't available and there is no introspection, passing an object of default values will at least provide type safety. No constraints will be available, but everything else will work.

Schema detection and tree shaking

It can be difficult to detect which of the validation libraries the schema belongs to at runtime. Therefore, it may be useful to handle the introspection in an adapter function, which also would help with tree shaking, quite important when we're about to support 14+ validation libraries. We only want to include the runtime for the library being used. Here's what it could look like:

import { zod } from 'sveltekit-superforms/adapters'

const form = await superValidate(zod(schema), data)

These ideas are not final, and help is much appreciated. Please open an issue at the repo on Github, or join the Discord server so we can have a chat in the #v2 channel. There are also a few 2.0 milestone issues that can be worth checking out.

Roadmap to version 2

There we have the plan for making Superforms support almost any validation library! A few tests have been made already and it looks like there should be no problems in making it happen.

I estimate that the validation part, superValidate, will be finished rather quickly, as the other libraries will do most of the heavy lifting there. The client part, superForm, is more intricate but a lot will be reused from version 1. Some parts are still dependent on Zod or have to be rewritten though, like the client-side validation, because they are frankly a bit messy. The test suite and browser automation tests must also be ported.

Donate to make it happen

Unfortunately, there's not enough time and money to do all this rapidly. Maintaining and giving support for version 1 takes up a bit of time already, but with donations, I can at least distribute the time and prioritize the development.

So if you want to see Superforms v2 happen, there are a few ways of donating on the Superforms website. Any amount helps, and a monthly donation of $10 or more will be listed on the Sponsors page. A huge thanks to the people that are sponsoring, or have donated in the past.

Whether you donate or not, you are welcome to the Discord server to have a chat, give a word of encouragement, and of course get help for the current version of Superforms. See you there!

Error handling in Contexts

As promised, the topic for today is error handling with the least amount of surprise. This could lead us to ask what is surprising when coding and debugging.

Code locality

DCI does an excellent job at locality - making the code understandable when looking at only a small portion of it. In the non-polymorphic, pattern-less locale of a DCI Context, you rarely have to seek outside it to understand how things are supposed to work.

Let's illustrate this with an example of the opposite. There is a problem with password handling in a web framework, and we have to figure it out. The entry point is found, but then things get a bit abstract:

class PasswordController extends Controller
{
  public function update(Request $request, UpdatesUserPasswords $updater)
  {
    $updater->update($request->user(), $request->all());
    return app(PasswordUpdateResponse::class);
  }
}

We see a short controller class that calls an updater. UpdatesUserPasswords is an interface, so next we have to find the implementations, briefly analyze them and start debugging to conclude which one is the problem. And then the process repeats, maybe the UpdatesUserPasswords implementation calls an UpdatesClient and an UpdatesDatabase interface, with respective implementations, and so on... you'll get the idea.

This abstraction is not only unexplanatory (an "update" method with an "updater" that will "update") but will lead us down a rabbit hole. Where are things happening? In the next layer of abstraction? Or parts of it here, and the rest in another place?

DCI does the opposite, by describing local and contextualized behavior. A Role is an interface but related to relevant behavior. You can see it as the DCI Role abstraction points toward the architecture of the system, instead of towards some general "update" notion that conceals the system behavior and mental model.

The 21st-century GOTO

Lack of locality can be confusing and lead to surprises, because the further we go away from a central location, the more we have to know about and mentally knit together all parts of the system - not a trivial task.

Now imagine that during all this, you're suddenly transported somewhere else and have to refocus and adjust to new surroundings.

This is what happens when a program jumps across reasonable boundaries, as in the following concepts:

• Events

• Exceptions

Arbitrary jumping across a program has since long been frowned upon, but it seems to have resurfaced in these concepts as a 21st-century GOTO. And we experience pretty much the same kind of surprise and confusion when getting lost in reality, as in program code: "Where am I? How did I get here?"

With DCI however, we have an effective way of protecting ourselves from these kinds of surprises, which is, as you may have guessed, to keep the program flow within the Context to the highest possible extent. Let's examine the "GOTOs" and see if and how they can be used in a DCI Context.

Events

Role contract events

If a Role contract contains some event subscribing method, be aware that any subscription to it finds the Context program flow at the mercy of a Roleplayer. This can be confusing and also break the mental model described by the RoleMethods, as it can suddenly interrupt the defined message flow.

Therefore, if you need to subscribe to an event, treat it as a one-off event if possible. For example, addEventListener has a once option. After the event is handled, you explicitly subscribe to it again, so it becomes a part of the message flow, keeping you in control of the program.

Context events

Exposing events in the public Context interface should at least warrant the question of why it is needed. Since a Context can be a RolePlayer in another Context, by exposing an event source, we potentially cause surprises in other Contexts.

Exceptions

Jumping from the well-defined message flow of a Context to some unknown place outside it violates the readability goal of DCI. Not even exceptions are exempt from this rule.

In the previous parts' example, we have started the system operation (an entry point) in a code block at the end of the Context:

{
  // System operation
  Messages_hide();
}

There was a reason for the code block: It provides a place for error handling. It can now be easily modified to

try {
  // System operation
  await Messages_hide();
} catch (e) {
  // TODO: Error handling
}

We can now assure that no errors will leak through the Context to another abstraction level. try/catch requires that we are using async/await for the RoleMethods, hence the added await keyword.

How the exceptions are handled varies, but in a web application, it's common to send errors to a logging service. It can be done at the top level, so it's not a strict requirement to catch and handle all errors, but as long as the errors are related to the Context it's a good practice, including being consistent about the approach that's taken.

The final rewrite of the SubmitForm Context

After making our SubmitForm Context use async/await, the final version looks like this:

import { log } from './log';

/** 
 * Submit a form and show error messages from the response.
 * @DCI-context
 */
async function SubmitForm(e: SubmitEvent) {
  if (!(e.target instanceof HTMLFormElement)) {
    throw new Error('No form found.');
  }

  //#region Form Role /////

  const Form: {
    action: string;
  } = e.target;

  async function Form_submit() {
    // Role contract call (Form.action)
    const response = await fetch(Form.action, {
      method: 'POST',
      body: new FormData(Form as HTMLFormElement)
    });

    const data = await response.json();

    for (const error of data.errors ?? []) {
      Messages_show(error); // Role interaction
    }
  }

  //#endregion

  //#region Messages Role /////

  const Messages: Iterable<{
    dataset: DOMStringMap;
    style: CSSStyleDeclaration;
  }> = e.target.querySelectorAll<HTMLElement>('[data-form-message]');

  async function Messages_hide() {
    Messages__set('none');
    await Form_submit(); // Role interaction
  }

  function Messages_show(name: string) {
    Messages__set('unset', name);
  }

  // Private RoleMethod (double underscore)
  function Messages__set(display: string, name = '') {
    for (const msg of Messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  }

  //#endregion

  try {
    log('Submit');
    e.preventDefault();
    await Messages_hide(); // System operation
    log('Done');
  } catch (e) {
    log(e);
  }
}

(Code with demo is available here on Stackblitz.)

Some regions have been added for the Roles, which can be folded in VS Code for a better overview in large Contexts.

Context initialization errors

The astute reader may have noticed that we're throwing an exception at the beginning of the Context - outside the try/catch block - which may look contradictory to what's been said, but this initial error checking is more like a contract or a constructor than part of the Context behavior, and if that fails, it's nothing we can handle and must relinquish control, since the initiator didn't fulfill the conditions for initializing the Context.

Reusable Roles?

Before finishing this part, we have to tie up a loose end from part 3, where I mentioned that the language Haxe has something called Abstract types, an interesting and useful feature that looks similar to Roles, but since it's a separate type, similar to mixins and extension methods, etc, it can stand on its own.

This can lead to the question if Roles can be reusable as separate types, but Roles have a name and responsibilities that make sense only in a certain Context, so they cannot. The DCI FAQ has a question dedicated to this topic, so we'll end this part with a quote from there:

A Shape can move and draw in a graphical context; a Cowboy can move, draw and shoot in a Western movie context. Having a Role — named however you like — that can draw and shoot does not make it a candidate for reuse in another Context.

As always, thank you for reading, just reach out if you have any questions!

Call me bold, but I'd say yes. You have common sense within you. You have experienced enough bad design to avoid disaster. And if you ever designed something bad, it was probably because you were stressed, or someone (your boss, a client, etc) made you do it.

"Sure, but still, only two rules?"

Yes. Maybe you've already read them. They can be found in one of the "must-read" books. But it's understandable if you missed them, there are plenty of other must-read books to read.

OK, bring them on!

All right, without further ado:

Make sure that: (1) the user can figure out what to do, and (2) the user can tell what is going on.

-- Don Norman, "The Design of Everyday Things"

There, you've read them; now take a minute to ponder about them.

That inner voice. Is it self-doubt, the endless marketing schemes, or silver bullet thinking that makes you reach for the latest advice, instead of simple, timeless advice?

"It's too simple," protests the inner voice from an unknown source. "Everything should be made as simple as possible, but not simpler." Now it's quoting Einstein and seems to gain a lot of confidence.

Before it convinces you, gently remind it that concrete advice and aphorisms are not on the same abstraction level, and one can hardly be used to dismiss the other.

Let's instead briefly look at the rules, one at a time, and see what insights we can gain.

1. Make sure that the user can figure out what to do

Here's a screen from a well-known application where everything is laid out before us.

Isn't it great to have everything available at your fingertips? You only need to remember the function of all buttons and the layout, and you'll have no trouble doing exactly what you want. Right? No?

The inner voice seems to agree with us this time, it's overwhelming. So let us ask ourselves a key question: What is the conflict with rule #1?

Of course, there are so many things on the screen that it's hard to figure out what to do. That was simple.

User context and noun-verb operations

That was indeed simple, because the user context is very important. If the user wants to crop an image, she should be able to figure out what to do in that context.

This goes hand in hand with a great piece of advice from Jef Raskin: Prefer noun-verb construction instead of verb-noun.

In this case, cropping an image will then become image-crop, translating UX-wise to:

1. First, select an image

2. Then select the crop command and its parameters

3. Commit the operation.

For every step, we can now reveal additional information to the user, to make her figure out what to do next. Compare that to the opposite, crop-image:

1. First, select the crop command and its parameters (must always be visible)

2. Then select an image (not anything else!)

3. Commit the operation.

Let's also say that the user is interrupted between steps 1 and 2 and comes back later, forgetting that a crop operation is ongoing. She clicks on a text paragraph, and an obscenely loud windows error sound reverberates through the room, making her drop the freshly brewed cup of tea over the desktop and her new $300 noise-canceling earbuds.

Way to go, verb... but hey, at least the UX didn't break rule #2! 😄

So many things follow from revealing things to the user based on noun context.

• ...And by having clearly visible buttons/links/clickable areas for the most obvious actions to take at the time

• And by pleasant typography

• And a well-thought-out color scheme

• And so on. You know this already.

Just ask yourself at every step of designing a user interface, can the user figure out what to do?

2. Make sure the user can tell what's going on

Interaction ahead! Now we're into real UX. Have you ever entered plenty of information into a website, clicked the submit button... and nothing happened. No wait, at the left bottom of the screen is our indicator of assurance:

Bless the browser for lightening the load of the designers, so they can hit the after-work early and look for the cute new girl at the office.

Isn't it ridiculous that the majority of websites can't at least provide feedback that their cheap hosting server is overloaded and will take up a bit of the user's precious time?

From now on we will respect the user more than that, right? But let's not break out the huge modal overlays already, let's see about the timing of notification first.

Response times

Jakob Nielsen has a useful piece of advice for us here, from Response Times: The 3 Important Limits:

• 0.1 second: The limit of feeling an instantaneous reaction from the system

• 1.0 second: The limit of feeling that the user is operating directly on the data

• 10 seconds: The limit of keeping the user's attention.

This means that if the server is lightning fast with a response time of around 0.1 seconds, we don't need to provide any feedback. That will just be a distraction.

After perhaps 0.2 seconds, we can provide feedback, maybe a loading spinner inside the button, and/or a "submitting" message next to it.

After 6-7 seconds instead of 10 (compensating for the internet attention span), we'll add an extra notice that something is taking more time than it should, but please be patient, dear user. We're thrilled that you're submitting your information to us.

Now apply this example to anything that goes on in your design.

The same goes for mistakes. If the user makes a mistake, make sure it's obvious that a mistake has been made, but it's not the end of the world.

• Add helpful error messages next to the form field

• Automatically scroll to the first error of a form, and place focus on the erroneous field

• After nailing rule #1, let switching contexts happen without confusion

• Etc!

Whenever the user does something, or if something takes time, make sure the user can tell what's going on.

We're at the end

This text is deliberately brief, because of what was said in the beginning:

You have common sense within you. You have experienced enough bad design to avoid disaster. And if you ever designed something bad, it was probably because you were stressed, or someone (your boss, a client, etc) made you do it.

This may get philosophical, but the message is deeper than what an article or a must-read book can convey. When we're not blinded by stress, ambition, competition or money, we can build on timeless principles instead of trends. We do that by connecting to ourselves and others, with empathy, respect and insights from deeper knowledge, distilled into pieces of advice that could be used as rules in the right circumstances. UX is a fundamental part of being human, our body, senses, perception and life itself, everything is there for us to use and understand.

You can do that, and by doing that you're making the world better even by coding a website, but I invite you to expand the concept to all areas of your life. So make sure that: (1) your fellow humans can figure out what to do, and (2) your fellow humans can tell what is going on.

This article will show you how to connect two modern, well-thought-out parts of the web app toolchain. Let's start with the framework.

Most people seem to agree that SvelteKit has succeeded in creating a both powerful and joyful web development experience. And with the recent 1.0 release, there's no question that it's our framework of choice here.

Edit: The code for this article is available on github here.

Creating the SvelteKit project from scratch

The only prerequisite is Node.js, which comes with its package manager npm. It's used here, but for a faster and overall nicer experience, install pnpm and substitute all npm and npx commands with pnpm below. Open a terminal in your project folder and initialize a new SvelteKit project called "i18n" with:

npm create svelte@latest i18n

At the first two prompts, select Skeleton project and Typescript syntax, the rest is up to you. Then we're installing its dependencies:

cd i18n
npm install

Installing the i18n library

Our i18n library of choice is called typesafe-i18n, selected because it gets so many things right, from syntax to output size. We will also install a package called npm-run-all to be able to update the translation files in parallel with running the SvelteKit dev server:

npm install -D typesafe-i18n npm-run-all

After that, we will generate the configuration file for the translation:

npx typesafe-i18n --setup-auto

This will generate a .typesafe-i18n.json in the root project folder, that we should edit to specify an outputPath field. This is because we want to use SvelteKit's convenient $lib alias so we can refer to the translation anywhere in the project. Open .typesafe-i18n.json and add it:

.typesafe-i18n.json

{
  ...
  "outputPath": "./src/lib/i18n/"
}

Finally, we will modify package.json to run typesafe-i18n and the vite dev server that SvelteKit uses at the same time:

.package.json

{
  ...
  "scripts": {
    "dev": "npm-run-all --parallel vite typesafe-i18n",
    "vite": "vite dev --open"
    ...
  }
}

As you may have noticed further down in the file, typesafe-i18n has been added to package.json already.

Before starting SvelteKit, let's quickly go through the different levels of translation that typesafe-i18n provides.

LLL, LL and L

There are three different levels to consider, the lowest being represented by the LLL object. It deals with a single translation string, transforming it to proper output. Knowing the translation string syntax is essential, but we won't use this object directly, since the next level is a more convenient way of outputting translated text in our SvelteKit app.

The LL object is much more suitable for the client, since it contains all strings for a specific locale (language settings with formatting rules) - we don't need to transfer all languages to the client, just the one we need.

Finally, the L object contains all available locales, making it more useful server-side.

We're going to use the LL object, which will be available to us in the auto-generated language files. So let's start up the dev server and see what happens:

npm run dev

Files have now been generated in src/lib/i18n, together with two example languages, en (the default) and de. Each language is represented by a string object that you can organize however you'd like, as a flat structure, or nested.

Also generated is a src/lib/i18n/i18n-svelte.ts file that exports a LL object. This is the one we're going to use, but first, given that we have two languages, how do we choose which one to load?

Using routing for language detection

Some apps will have the current locale stored in user settings or a cookie, but we will take the route approach, having the locale in the first portion of the URL, like /de/some/page. (Changing to another way of detecting the locale is quite simple, as you will see later.)

SvelteKit's flexible routing system makes this quite easy. We're gonna make use of a route like this:

[lang]

Square brackets signify a route parameter, so we can use parts of the route dynamically. In this case, we want to access the first part of the route as the lang parameter. But we don't want it to be required, since the default language en shouldn't have its locale code prefixed. With double brackets it will be optional, meaning that routes like /de/some/page and /some/page will result in the same page being loaded.

Let's display a translation string, but first some cleanup: Delete the route files in src/routes so they won't conflict with the new route. Then create the route directory src/routes/[[lang]] (with double brackets) and a +page.svelte file inside it:

src/routes/[[lang]]/+page.svelte

<script lang="ts">
  import { LL } from '$lib/i18n/i18n-svelte';
</script>

<h1>{$LL.HI({name: "World"})}</h1>

If you open the project in a browser, you'll see a message blink by quickly. This is because the default locale loads automatically on the server, but not on the client.

We don't have a layout yet, but a +layout.ts file can be quite useful here, since (from the SvelteKit docs) "+page.js and +layout.js files export universal load functions that run both on the server and in the browser".

With a top-level layout file, we make sure the current locale is always loaded for every page below it, both on the server and client. This is the place where we want to detect the locale based on the route. Let's start simple:

src/routes/+layout.ts

import type { LayoutLoad } from './$types';

export const load = (async (event) => {
  return event.data;
}) satisfies LayoutLoad;

This minimal file just passes on the event data from a future +layout.server.ts file. And the event parameter contains a params property with the lang route that we specified earlier.

Locale detection

Instead of using event.params.lang directly to set the locale, a detectLocale function is available from the generated i18n files. It's preferred to use since we can supply it with a matcher function, which will return a strongly typed locale (the default if the matcher fails), so we don't have to check for incorrect values. Let's use it:

src/routes/+layout.ts

import type { LayoutLoad } from './$types';
import { detectLocale } from '$lib/i18n/i18n-util';

export const load = (async (event) => {
  const locale = detectLocale(() => [event.params.lang ?? '']);
  // TODO: Load and set locale
  return event.data;
}) satisfies LayoutLoad;

Now we have the locale, but we must load it and set it before it can be displayed on the client. Fortunately, the generated files have us covered. First, we'll use the loadLocaleAsync utility function, then we use a Svelte-specific setLocale to populate the LL object we used earlier. Here's the completed layout file:

src/routes/+layout.ts

import type { LayoutLoad } from './$types';
import { loadLocaleAsync } from '$lib/i18n/i18n-util.async';
import { setLocale } from '$lib/i18n/i18n-svelte';
import { detectLocale } from '$lib/i18n/i18n-util';

export const load = (async (event) => {
  // Detect the locale
  const locale = detectLocale(() => [event.params.lang ?? '']);
  // Load it
  await loadLocaleAsync(locale);
  // Set it
  setLocale(locale);

  return event.data;
}) satisfies LayoutLoad;

Now open the front page, and you should see the translation string. Change the url to /de and the german version will load.

Adding translation strings and another page

Adding more translation strings and routes is as easy as adding to the src/lib/i18n/en/index.ts file and its de counterpart, following the syntax of typesafe-i18n. It makes things like plural rather simple, which could be a pain to implement by yourself:

src/lib/i18n/en/index.ts

const en: BaseTranslation = {
  ...
  APPLES: '{apples:number} apple{{s}}',
};

We'll use this soon, but first, we need to translate it into german. When opening the corresponding src/lib/i18n/de/index.ts file, you'll be notified that the APPLES property is missing, which is a nice reminder to get. But we have another problem, the singular and plural of apple are spelled differently in german. Well, no problem:

src/lib/i18n/de/index.ts

const de: Translation = {
  ...
  APPLES: '{apples} {{Apfel|Äpfel}}',
};

Note that unlike the en file, we don't have to specify the type of the {apples} argument. Now let's create the new route by adding two folders and files:

src/routes[[lang]]/apples/[amount]/+page.ts

import type { PageLoad } from './$types';

export const load = (async (event) => {
  return { 
    apples: parseInt(event.params.amount) 
  };
}) satisfies PageLoad;

src/routes[[lang]]/apples/[amount]/+page.svelte

<script lang="ts">
  import { LL } from '$lib/i18n/i18n-svelte';
  import type { PageData } from './$types';

  export let data: PageData;
</script>

<h1>{$LL.APPLES(data)}</h1>

Try it out by browsing to /de/apples/2 for example. Convenient, isn't it?

Linking between pages

We have pretty much covered the basics now, but one thing that's easy to overlook is how to link between pages while keeping the locale intact. The solution is to translate the links as well, prepending the locale before the actual route:

src/lib/i18n/en/index.ts

const en: BaseTranslation = {
  ...
  LINK: '{0}', // No prefix needed
};

src/lib/i18n/de/index.ts

const de: Translation = {
  ...
  LINK: '/de{0}', // Prepending the locale
};

Now we can link back to the start page:

src/routes/[[lang]]/apples/[amount]/+page.svelte

<h1>{$LL.APPLES(data)}</h1>

<a href={$LL.LINK('/')}>Back to start</a>

And it should be no problem for you to translate the "Back to start" phrase now if you'd like!

Matching only the defined languages

We have a slight problem though: We can enter anything as the "lang" route parameter, and the start page will be loaded in english. We'd like any non-existing language to return a 404 instead.

This can be done using a route matcher for matching only the languages we have a translation for. We're using the locale data from i18n-util to exclude the default locale and check if the parameter matches one of the others:

src/params/langCode.ts

import type { ParamMatcher } from '@sveltejs/kit';
import { baseLocale, locales } from '$lib/i18n/i18n-util';
import type { Locales } from '$lib/i18n/i18n-types';

export const match: ParamMatcher = (param) => {
  return param !== baseLocale && locales.includes(param as Locales);
};

The name of this file (without extension), langCode, is what we should use in the route name. So rename the [[lang]] route directory to [[lang=langCode]] and try to browse a non-existing locale. A 404 should be the result. The same could be done with the [amount] route parameter, using a matcher that checks for an integer.

One final challenge: Using a cookie instead of routes

To keep the routes clean, you may want to store the selected locale in a cookie instead. This isn't too hard to do, but it requires a change; the src/routes/+layout.ts file doesn't have direct access to cookies, so we need to use an additional +layout.server.ts file, with some minor changes to +layout.ts:

src/routes/+layout.ts

import type { LayoutLoad } from './$types';
import { loadLocaleAsync } from '$lib/i18n/i18n-util.async';
import { setLocale } from '$lib/i18n/i18n-svelte';

export const load = (async (event) => {
  // Locale now comes from the server instead of the route
  const locale = event.data.locale;
  // But we load and set it as before
  await loadLocaleAsync(locale);
  setLocale(locale);

  return event.data;
}) satisfies LayoutLoad;

src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types';
import { detectLocale } from '$lib/i18n/i18n-util';
import { redirect } from '@sveltejs/kit';

const langParam = 'lang';

export const load = (async (event) => {
  // Using a GET var "lang" to change locale
  const newLocale = event.url.searchParams.get(langParam);
  if (newLocale) {
    event.cookies.set(langParam, newLocale, { path: '/' });
    event.url.searchParams.delete(langParam);
    // Redirect to remove the GET var    
    throw redirect(303, event.url.toString());
  }

  // Get the locale from the cookie
  const locale = detectLocale(() => [event.cookies.get(langParam) ?? '']);
  return { locale };
}) satisfies LayoutServerLoad;

Even cookie handling is trivial with SvelteKit! We're now passing on the locale from the server to the universal +layout.ts file, which will use event.data.locale instead of event.params.lang as before. And everything is strongly typed, again thanks to SvelteKit.

Test this out by browsing to:

/apples/1?lang=de

This also means that we don't need the $LINK route translation anymore, so it can be removed.

Conclusion

I hope this article has helped show that i18n is quite manageable once you pass the "setup hurdle". It's great to see that both typesafe-i18n and SvelteKit are leveraging Typescript to give useful hints about route parameters, missing translation strings, etc.

To dive deeper into typesafe-i18n, check out its Table of Contents, the SvelteKit documentation is available here, and let me know if you have any questions or comments. Thanks for reading!

We talked a lot about Roles in the previous part, concluding that Roles are a quite natural way of expressing ourselves in code. This has led to many attempts at adding Roles to languages without introducing additional syntax. This has also been a huge source of misunderstanding regarding DCI, so let's clear this one once and for all.

DCI Roles cannot be wrappers

Who needs the underscore RoleMethod convention? Let's use objects instead for the example in Part 3:

const Messages = (function(
  Messages: {
    [Symbol.iterator]: () => IterableIterator<HTMLElement>;
  }
) {
  function set(display: string, name = '') {
    for (const msg of Messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  }
  return {
    show(name: string) {
      set('unset', name);
    },
    hide() {
      set('none');
    },
  };
})(e.target.querySelectorAll('[data-form-message]'));

// Now we're free to use the Role with normal method syntax:
Messages.hide()

This seems to be working but unfortunately isn't. This has been the number one obstacle when trying to understand DCI: Failing to understand that you cannot wrap a Role in, or substitute it for another object. By doing that you are violating object identity, which could work in many cases, but not all, and that kind of uncertainty is not what we want in software.

The problem is that any other part of the program, and that can be a huge part considering the number of external dependencies of a project, doing an identity check (== or ===) on the Messages Role will now fail this check, even though it was supposed not to.

This FAQ entry explains the whole thing in more detail, and I've made an example on Stackblitz that shows how these bugs can appear, even in a strongly typed language like TypeScript.

Now that we have gotten this out of the way, let's move on to more interesting things.

Adding actual interaction

A question was asked at the end of Part 3: If there is only one Role, can there be interaction?

Interaction presupposes more than one part, so the answer seems to be no, and this is also the case with DCI. Programs with minimal object interaction are probably just as readable without Roles, data transforming with functional programming comes to mind here as well. But it's worth considering that something simple can grow more complicated, and the more variables introduced, the greater the chance that some interaction happens between them.

Looking at our SubmitForm Context again, is it too simple for Roles?

// @DCI-context
function SubmitForm(e: SubmitEvent) {
  e.preventDefault();
  if (!(e.target instanceof HTMLFormElement)) 
    throw new Error('No form found.');

  // Role
  const Messages : Iterable<HTMLElement> = 
    e.target.querySelectorAll('[data-form-message]');

  // RoleMethods
  const Messages__set = (display: string, name = '') => {
    for (const msg of Messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  };

  const Messages_show = (name: string) => Messages__set('unset', name);

  const Messages_hide = () => Messages__set('none');

  {
    // System operation
    const form: HTMLFormElement = e.target as HTMLFormElement;

    Messages_hide();
    fetch(form.action, { method: 'POST' })
      .then((response) => response.json())
      .then((data) => data.errors?.forEach(Messages_show));
  }
}

Well, something seems to interacting in the system operation:

{
  // System operation

  // We're creating a new variable here:
  const form: HTMLFormElement = e.target as HTMLFormElement;

  // This is the actual system operation - a RoleMethod call
  Messages_hide();

  // Form submit behavior
  fetch(form.action, { method: 'POST' })
    .then((response) => response.json())
    // Interaction with Messages.show
    .then((data) => data.errors?.forEach(Messages_show));
}

I'd say we have created a Role without really noticing:

• An identifier (form) is created and assigned

• It has behavior (submit the form)

• It interacts with the Messages role.

This means that we in principle have two Roles, and therefore interaction! Let's modify the Context to use a Form Role instead:

// @DCI-context
function SubmitForm(e: SubmitEvent) {
  e.preventDefault();
  if (!(e.target instanceof HTMLFormElement)) 
    throw new Error('No form found.');

  // Role
  const Form: {
    action: string;
  } = e.target;

  // RoleMethods
  const Form_submit = () => {
    Messages_hide();
    fetch(Form.action, { method: 'POST' })
      .then((response) => response.json())
      .then((data) => data.errors?.forEach(Messages_show));
  };

  // Messages role omitted, it's unchanged.
  // ...

  {
    // System operation
    Form_submit();
  }
}

It's now more apparent what's going on. The Role contract is literal, so we can immediately see that the object playing the Form Role only needs an action property to do that. And remember that the action property is protected from access by the rest of the Context. If we want to access it, we have to be explicit and use the Form's public RoleMethods.

Distributing the interaction

What we have done now, however, is to create an imperative, all-knowing Role that limits the DCI idea of describing a network of interacting objects. Putting the interactions in one place like this is a step back to procedural programming (like the previous system operation, though perhaps it was simple enough to get away with it).

Older languages like Fortran and Pascal worked in sequence and told in detail to the computer what to execute. This is not what we want, since objects in the network are non-static entities. By strictly organizing them, telling them what to do and handling their return values, we prevent interaction and communication. This FAQ entry explains in more depth.

Instead of limiting communication, let's think of how our objects could interact and communicate more dynamically. Here is a breakdown of the code in its current, procedure-like fashion:

1. Tell the messages to hide

2. Fetch the form action and return the errors

3. Tell the messages to show the errors

Let's instead distribute this algorithm in an object-oriented fashion:

Now the RolePlayers are communicating in a message-passing manner, which is not only more connected to mental modeling and DCI concepts, it is also more genuine:

1. User: Messages, can you hide?

2. Messages: (Hiding) Form, can you submit?

3. Form: (Submitting) Messages, can you show these errors?

4. Messages: Hey User, here are some error messages.

Now we're asking, not telling. By asking, we get rid of the assumption that the object can always do what we want (a more reasonable error handling, in other words). We will talk more about error handling in the next part.

With this, I think we're ready to update the Context (code on Stackblitz).

// @DCI-context
function SubmitForm(e: SubmitEvent) {
  e.preventDefault();
  if (!(e.target instanceof HTMLFormElement)) 
    throw new Error('No form found.');

  // Role
  const Form: {
    action: string;
  } = e.target;

  // RoleMethods
  const Form_submit = async () => {
    const response = await fetch(Form.action, {
      method: 'POST',
      body: new FormData(e.target as HTMLFormElement),
    });
    const data = await response.json();

    // Role communication/interaction
    data.errors?.forEach(Messages_show);
  };

  // Role
  const Messages: Iterable<HTMLElement> = 
    e.target.querySelectorAll('[data-form-message]');

  // RoleMethods
  const Messages_hide = () => {
    Messages__set('none');
    // Role communication/interaction
    Form_submit();
  };

  const Messages_show = (name: string) => {
    Messages__set('unset', name);
  };

  const Messages__set = (display: string, name = '') => {
    for (const msg of Messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  };

  {
    // System operation
    Messages_hide();
  }
}

The interactions now follow our mental model very closely. For further analysis, tracing a code path through the Context for this specific Interaction can be done with a sequence diagram:

"Rewiring" the Context

The flexibility of a distributed algorithm like this will be more evident as the system grows. By avoiding return values (though they are not forbidden), the parts of the system become more modular, and as functionality changes, we can more easily "rewire" the interactions similar to patching an audio effect rack, where a cable can send messages to another part of the rack.

Rewiring is much harder when we rely on return values to tell the system what to do next. It creates a coupling to the return value type, takes us away from the idea of mental modeling, and invokes the imperative programming style that isn't very object-oriented.

Context visualization

Looking at physical cables we can see how messages could travel, so it can help visualize the system until it gets too messy. Being able to pass messages without physical cables avoids the mess, but on the other hand, makes debugging less practical! Previously we've had trouble determining what part of the system to diagram since the behavior was spread out through multiple abstraction boundaries. The boundary of a Context though, as a distinct unit of system behavior, makes it appropriate for visualization tools to display its interactions, as I've experimented with earlier:

The Roles have different colors, the inner circle contains RoleMethods, and behind them, in the outermost layer, are the Role contract fields. I can put an interactive diagram online if there is enough interest.

In the next part

In the next part of this series, we will look at Context error handling with the least amount of surprise. See you there!

You have probably used Roles many times before

Roles are the central locus of a DCI Context, and chances are that you unknowingly have used them before. Let's take a look at a more realistic example: An AJAX form event handler that will display validation messages, but they should all be hidden when submitting the form and displayed when the response arrives.

The initial code could be something like this:

function submitForm(e: SubmitEvent) {
  e.preventDefault();
  if (!(e.target instanceof HTMLFormElement)) 
    throw new Error('No form found.');

  const messages =
    e.target.querySelectorAll('[data-form-message]') 
      as NodeListOf<HTMLElement>;

  // ...to be continued

And from there, you want to show and hide the messages, so you create functions for that:

  const hideMessages = () => {
    messages.forEach((m) => (m.style.display = 'none'));
  };

  const showMessage = (name: string) => {
    messages.forEach((m) => {
      if (m.dataset.formMessage == name) m.style.display = 'unset';
    });
  };

But these functions have too much in common not to be factorized, so you do that with a setMessage function:

  const setMessage = (display: string, name = '') => {
    for (const msg of messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  };

  const showMessage = (name: string) => setMessage('unset', name);
  const hideMessages = () => setMessage('none');

And finally, a bit of simplified code for the actual form submission:

  const form: HTMLFormElement = e.target as HTMLFormElement;

  hideMessages();
  fetch(form.action, { method: 'POST' })
    .then((response) => response.json())
    .then((data) => data.errors?.forEach(showMessage));
}

Problem solved, for now. Let's say that the next feature request is to automatically scroll to the topmost error message. So you'll add another function or two, copy/paste a helper function from Stack Overflow, and everything's fine again for a while. And the next is to scratch the itch of data-form-message being hardcoded, so options are introduced. And so on...

Adding functionality in this manner makes our mini-system quickly start to fragment. Variables will be spread throughout, with a multitude of functions that are used from anywhere within it. Let's look at the initial ones:

• setMessage, showMessage, hideMessages

Both namewise and by their usage, they're related to the messages variable that we created earlier, which is an identifier for an array of HTML elements. So maybe they should be grouped like methods on an object, pointing us to a class as a possible solution?

Classes to the rescue?

class FormMessages {
  readonly messages: NodeListOf<HTMLElement>;

  constructor(form : HTMLFormElement) {
    this.messages = form.querySelectorAll('[data-form-message]');
  }

  set(display: string, name = '') {
    for (const msg of this.messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  }

  show(name: string) {
    this.set('unset', name);
  }

  hide() {
    this.set('none');
  }
}

One problem with classes, with their static set of functionality and relationships, is that they are falling into what the authors of DCI call "Restricted OO". By introducing a separate class, we'll be confronted by FormMessages instead of a literal type, which means we have to look up and grasp the intricacies of that class before being able to fully understand what our form submit function does. Check the link for more details, it's quite a read.

Objects to the rescue, then?

We're transpiling to Javascript, which can create objects in other ways than classes, so can we circumvent the class issue? (no, not the real-world issue!)

Unfortunately not; the problem with objects, instantiated by classes or not, is that they are encapsulating three things: state, behavior and identity, but in our case, we only need one.

• State is already contained in a NodeListOf<HTMLElement>

• That list has identity as well, which can be tested with an equality operator, and could lead to very subtle bugs if identity is violated by wrappers

• All we need is the behavior we defined earlier: setMessage, showMessage, hideMessages.

We are clearly missing a language feature that handles our case, and as you probably have figured out, that would be a DCI Role.

Roles to the rescue!

If Roles would be a built-in feature of Typescript, our Messages Role could perhaps look like this:

// ...inside a Context

role Messages {
  // Role contract
  Iterable<HTMLElement>;

  // RoleMethods
  show(name: string) {
    set('unset', name);
  }

  hide() {
    set('none');
  }

  private set(display: string, name: string) {
    for (const msg of self) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  }
}

...but lacking this, we have to make compromises like the lamented underscore convention. Our faux-Role in Typescript looks like this:

const Messages : Iterable<HTMLElement> = 
  e.target.querySelectorAll(messageSelector);

// RoleMethods
function Messages_show(name: string) {
  Messages_set('unset', name);
}

function Messages_hide() {
  Messages_set('none');
}

function Messages_set(display: string, name = '') {
  for (const msg of Messages) {
    if (name && msg.dataset.formMessage != name) continue;
    msg.style.display = display;
  }
}

This is the reason the ESLint DCI library was created - to ensure the closest possible emulation of Roles.

Rewriting the form validation

This part is getting long enough, so let's wrap it up by rewriting the form submit function as a DCI Context:

// @DCI-context
function SubmitForm(e: SubmitEvent) {
  e.preventDefault();
  if (!(e.target instanceof HTMLFormElement)) 
    throw new Error('No form found.');

  // Role (Data)
  const Messages: Iterable<HTMLElement> = 
    e.target.querySelectorAll('[data-form-message']);

  // RoleMethods (System behavior)
  function Messages_show(name: string) {
    Messages__set('unset', name);
  }

  function Messages_hide() {
    Messages__set('none');
  }

  function Messages__set(display: string, name = '') {
    for (const msg of Messages) {
      if (name && msg.dataset.formMessage != name) continue;
      msg.style.display = display;
    }
  }

  {
    // System operation (Interaction)
    const form: HTMLFormElement = e.target as HTMLFormElement;

    Messages_hide();
    fetch(form.action, { method: 'POST' })
      .then((response) => response.json())
      .then((data) => data.errors.forEach(Messages_show));
  }
}

The code is available on Stackblitz as usual.

Connecting back to the start - "You have probably used Roles before" - we've been doing it all the time, creating an identifier and functions with related behavior to it, but lacking the language feature it's very hard to see it - and honestly very hard to live without when you've grasped the concept of Roles.

It's very rare to see Role-like concepts in programming languages today, but the closest I've seen is Haxe with its Abstract types, though that cannot be a real DCI Role because of a reason that will be explained later. (On the other hand, Haxe has other features that enable true DCI.)

Private RoleMethods

One last thing: A modification made to the code is Messages__set. The double underscore declares a private RoleMethod, which further encapsulates behavior only related to a Role. In this case, Messages.set was made to prevent code duplication, and we don't want other Roles, or the Context itself, to use it. A Role should only expose what's purposeful in its interaction with others in a Context, which raises an important question: If there is only one Role, can there be interaction?

This question will be answered in the next part. Keep reading in Part 4!

Bonus points

The only real DCI language out there, trygve, is taking an interesting approach to iterables by defining Role vectors, which map behavior to one item at a time. Read more about it, and about DCI in depth, in the comprehensive trygve user manual, available here.

Users browsing the site

For normal browsing (GET requests), a user-friendly message should be displayed. A thought could be to redirect users to a /maintenance route, but unexpected redirects is not a very nice UX. The route should not change, which means that we should use a common +layout.svelte component to display the message.

API access

If your site has an API defined with +server.ts files (docs here) these won't use a layout file, so they must be handled separately. It's probably unlikely that the API will be used for browsing, so a 503 Service Unavailable could be returned immediately, which is especially important in this case, since we don't want any API requests to go through and potentially modifying the database when we're doing maintenance!

Form data posting

This one is easy to overlook, but possibly the most important: A user posting form data to your site is very valuable, they could be finishing up a purchase, for example. So we need to treat these with the highest respect - if their data is lost in any way because of the maintenance, we've probably lost a customer.

This means that we need to:

• Prevent redirections
• Prevent clearing of the form
• Display a message that they could try again soon.

SvelteKit has the nice feature of Progressive enhancement, which takes user agents with no javascript into account.

Unfortunately, without javascript the browser will reload the page, and unless we do some advanced checking for maintenance mode later in the request, and restoring the form data without any other action taken, there's not much to do here.

If javascript is enabled though, we can take advantage of the progressive enhancement to prevent data loss, and that's what we will focus on, given that the majority of the users should have javascript enabled. But before we look into that, let's see if we can make things simpler.

Simplifying based on request method

A simplification could be made by assuming that GET requests won't modify anything critical in the system. If the site collects advanced statistics this may be a faulty assumption, but noting that, we're left with a simpler use case:

1. If GET - Display a friendly error message
2. If not GET - Return a JSON error message

This works because we want to return a 503 status code in both cases, which will cover our three scenarios:

Since HTTP status 503 means temporary unavailable, the API consumers should be able to handle that in both cases, even if they get a html page in the case of a GET request. Browsers will display the friendly message either way.

For form posting, returning HTML will mess up the client-side response, which expects JSON (we are ignoring the non-javascript users, as said) so we want to return something that the browser understands. SvelteKit has an ActionResult type which seems useful here. Let's piggy-back on that and add the use:enhance action, and we should probably be home free.

But haven't we forgotten something? How do we even put the site into maintenance mode?

Setting the site mode

We'd like to set some kind of MODE variable in the system, that will be read very early in the app and handled accordingly. This is not just about maintenance mode, but others as well. For example:

• development mode will have debug info and tools enabled
• staging mode will have source maps and design feedback tools enabled
• production mode will have bug reporting tools and analytics enabled

There could be all sorts of combinations between these that must be configured depending on the mode.

With NodeJS, Vite and SvelteKit we have a couple of modes already available, but there are a few issues with them:

• The NODE_ENV environment variable - but setting it to anything else than production or development could be problematic
• Vite's MODE, available through import.meta.env.MODE - could be anything, but must be set at build-time, so we can't change it while the site is running.

It looks like we have no other choice than to use something else. You have probably figured out that environment variables is perfect for this, given their speed of access and the multiple ways they can be updated.

But what should it be called? Naming is always hard. Using MODE directly can create confusion with the Vite variable. So I'm going for APP_MODE, and will specify all valid values in a template .env file:

.env

# development, staging, production, maintenance
APP_MODE="development"

# development, production
NODE_ENV="development"

(NODE_ENV is undefined as default, so we'll set that one too.)

Finally, we're ready to code!

Starting on top with hooks

Catching requests early is best done through src/hooks.server.ts in your SvelteKit app. This is where we want to respond with a 503 and a friendly message in HTML or JSON format, depending on request method. Let's dig in! The code is available on Stackblitz.

src/hooks.server.ts

import { env } from '$env/dynamic/private';
import type { Handle } from '@sveltejs/kit';
import type { ActionResult } from '@sveltejs/kit';

export const handle: Handle = async ({ event, resolve }) => {
  if (env.APP_MODE !== 'maintenance') return resolve(event);

  // Non-GET requests should not pass through.
  if (event.request.method !== 'GET') {
    const error = { status: 503, statusText: 'Maintenance mode.' };
    const actionResult: ActionResult = { type: 'error', error };
    return new Response(JSON.stringify(actionResult), {
      ...error,
      headers: { 'Content-Type': 'application/json' }
    });
  }

  // For GET requests, +layout.svelte will show a friendly error,
  // so we should render the response and make sure that maintenance 
  // mode is respected there as well.
  const response = await resolve(event);

  // Replace appropriate parts of the response with 503.
  return new Response(response.body, {
    headers: response.headers,
    status: 503,
    statusText: 'Maintenance mode'
  });
};

Displaying the message in +layout.svelte

As said, we need to use +layout.svelte to display the message, but there is a problem: We can't access APP_MODE directly from there since it's a server-side variable only. And we probably don't want to expose that value to the world, so we need a +layout.server.ts file to read and transform that value:

src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types';
import { env } from '$env/dynamic/private';

export const load: LayoutServerLoad = async () => {
  switch (env.APP_MODE) {
    case 'staging':
    case 'production':
    case 'development':
      return { maintenance: false };

    case 'maintenance':
      return { maintenance: true };

    default:
      throw new Error('Invalid app mode!');
  }
};

This helps us ensure that APP_MODE is set to a correct value. The returned data structure can also be used for other cases, for example adding external javascript in certain modes. Using it is very simple:

src/routes/+layout.svelte

<script lang="ts">
  import type { LayoutData } from './$types';
  export let data: LayoutData;
</script>

{#if data.maintenance}
  <h1>Maintenance mode</h1>
  <p>We'll be back in a few minutes.</p>
{:else}
  <slot />
{/if}

With this, the users can simply reload the site when the message appears, instead of being redirected somewhere else and losing the current URL.

So we have covered API usage and browsing. Now let's tackle the more difficult, but very important part - form posting.

Preventing data loss at forms

We all know how annoying this can be, so it must be prevented. Let's test it by setting up a simple form on the default page, with a form action:

src/routes/+page.svelte

<script lang="ts">
  import type { ActionData } from './$types';
  import { enhance, applyAction } from '$app/forms';
  import { page } from '$app/stores';

  export let form: ActionData;
</script>

<form method="POST" use:enhance>
  <p>Name: <input name="name" type="text" value={form?.name ?? ""} /></p>
  {#if form?.errors?.name}
    <p>Name must be at least 4 characters long.</p>
  {/if}

  <p><button>Submit</button></p>
</form>

src/routes/+page.server.ts

import type { Actions } from './$types';
import { invalid } from '@sveltejs/kit';

export const actions: Actions = {
  default: async (event) => {
    // For testing:
    // throw new Error('Simulating error/maintenance mode')

    const data = await event.request.formData();

    const values = {
      name: data.get('name')?.toString() ?? ""
    };

    const errors = {
      name: values.name.length < 4
    };

    if (Object.values(errors).some((e) => e)) {
      return invalid(400, { ...values, errors });
    }

    return { status: 'success' };
  }
};

This should work as expected, but if we uncomment the throw new Error line, or set APP_MODE=maintenance (which is difficult without making a production build, hence the throw shortcut), we're directly taken to the error page, losing all form data.

This means that we have to use the callback for use:enhance to avoid redirection. Change the form element to this:

src/routes/+page.svelte

<form method="POST" use:enhance={() => {
  return async ({form, result}) => {
    if(result.type !== "error") {
      if(result.type === 'success') form.reset()
      applyAction(result)
    }
    else applyAction({
      type: 'invalid',
      status: Math.floor(result.error.status) || 500
    })
  }
}}>

This will update the form as usual unless an error occurs, in which case it will treat the result as an invalid state, which will not render the error page. The Math.floor trickery is to ensure an integer for the status value (thanks Sanchithasr).

Try it out, and you'll see that we're not redirected anymore, but there is nothing notifying the user that the site is down. Fortunately we have $page.status available that can be used for this. We could even use the $page.form to display a success message while we're at it. Add this above the form:

src/routes/+page.svelte

{#if $page.status >= 500}
  <p><b>Server error, please wait a bit and try again.</b></p>
{:else if $page.form && $page.status == 200}
  <p>Form posted successfully!</p>
{/if}

Final notes

It was quite a bit of work to have a maintenance mode that will cause the least amount of annoyance for our users. The use:enhance part could be factored out into its own function so it can be used on all forms, but I think it its default behavior should be not to "redirect" to an error page, since staying on the same page without reload is one of the points of using use:enhance! I've posted an issue about it on Github, so we'll see what the kind SvelteKit team says.

About API requests: In case you really want to return JSON with API requests instead of the layout html, hopefully your API uses a route like /api/..., which mean that you can test for that in hooks.server.ts:

if (event.request.method !== 'GET' || event.routeId.startsWith('/api/')

A final thing that we haven't tackled is to make the form status message disappear when re-submitting the data. Again, it's nice UX to make the message disappear/change while waiting for the response, but I haven't found a way to handle this without a separate variable on the page, which would be nice to avoid. Let me know if you have a way of solving this.

We're at the end, so thanks for reading, I hope you can find this useful. Thoughts, comments, suggestions, please let me know!

This second part is more theoretical, but some background is needed to understand why we should consider coding in a quite different way than what we are used to.

Who do we code for?

I think it's fair to say that most of the time, we code for others. All but the tiniest of hobby projects will eventually reach someone else than the programmer - a user. From that point of view, a priority should be to design software that is both understandable and usable for those people that aren't programmers.

Once upon a time, this was common sense. Back in the 70s, in Palo Alto, people like Alan Kay were researching how to make computers as easy as possible to use, with the vision that the computer, with its speed and processing power, could be an extension of the human mind. It was an exciting time, when design, psychology and other disciplines melted together in this new medium.

The key idea was how to make the computer think as the user, not the other way around, as unfortunately happened when engineers after the 70s decided that their structures are what software should be based upon, not the user's mind[1]. This is something that DCI tries to remedy.

DCI and mental models

If we could design a system that reflects the user's mind in program code, that would be a huge step forward. The programs would look different as well, since you cannot find many users that speak about programming-related things like "abstract factories", "visitors", "polymorphism" or even "return values" when they describe their view of a system.

Therefore, if we want to make the computer think as the user, we need to put things like patterns and classes in the back seat, or at least consider them as plumbing - useful, but hidden and not in the way of the user and the architecture that we're trying to build.

With this in mind, let's see how a user could describe a program:

"I want to proclaim something to the world."
Like a phrase?
"Yes, I want to proclaim a phrase to the world!"
And who are you?
"I'm a speaker, and I want to proclaim a phrase to the world."
What should the world do with your proclamation?
"It should listen to it."
What if it won't?
"Well, it should at least note it."

Let's compare that to a slightly modified version of the Context from part 1:

/**
 * @DCI-context
 * A speaker proclaims a phrase to the world, that dutifully notes it
 */
function HelloWorld(
  // Roles - Objects required for the Context functionality
  Speaker: { phrase: string },
  World: { log: (msg: unknown) => void }
) {
  // RoleMethods - Describing the interaction between objects

  function Speaker_proclaim() {
    World_note(Speaker.phrase);
  }

  function World_note(phrase: string) {
    World.log(phrase);
  }

  {
    // System operation - Starts execution of the Context
    Speaker_proclaim();
  }
}

Looking at the RoleMethods, we have a Speaker that proclaims a phrase, and a World that notes it. Seems to be quite a match of the description, doesn't it?

What we have done is expressed in code the user's mental model of a Hello World program. The Wikipedia definition of a Mental model as "an explanation of someone's thought process about how something works in the real world" works in this case, but only scratches the surface. Indi Young puts it in much more detail in her excellent book "Mental Models":

"Designing something requires that you completely understand what a person wants to get done. [...] You need to know the person’s goals and what procedure and philosophy she follows to accomplish them. Mental models give you a deep understanding of people’s motivations and thought-processes, along with the emotional and philosophical landscape in which they are operating."

In a mental model, the user quite consistently speaks about objects as Roles. Let's examine that.

The difference between thinking and doing for users

Remember how we executed this Context? We passed two simple objects to it:

const you = { phrase: "Hello, World!" }

HelloWorld(you, console)

However, in this Context, you transform into a Speaker and the console into the World. This is a key difference between thinking and doing. When a user thinks about something (data), objects become what they are. You is a simple object that represents a person with a phrase. But when it's time to do something (function), we label things differently. The person-object plays the Role of a Speaker, and the console isn't just a computer screen anymore, according to the user it's the World!

You could say that we are upholding an illusion here, just as an actor playing a believable Hamlet is upholding that illusion, to the enjoyment of the audience. And this is what happens when the mental models match. When you play a computer game and the controls are matching your idea of piloting a starship, the controller becomes an extension of your mind, and the illusion of being a starship pilot is upheld, for your enjoyment. Which was the goal of the humane computer research, back in the 70s.

Welcome to DCI, where we express and uphold mental models for the sake of the most important part of the system - the user.

In the next part, we will get much more practical with modeling a realistic example of a DCI Context. Keep reading in Part 3.

Footnotes

[1] For a deeper dive into users and computers, see my article Rediscovering MVC.

What is DCI?

DCI was invented by Trygve Reenskaug, also the inventor of MVC, and has been furthered together with renowned OOP writer James O. Coplien since 2009.

From a high level, DCI strives to achieve the following:

• Separating what the system is (data) from what it does (function). Data and function have different rates of change so they should be separated, not as it currently is, put in classes together.

• Create a direct mapping from the user's mental model to code. The computer should think as the user, not the other way around.

• Make system behavior a first class entity.

• Great code readability with no surprises at runtime.

To begin our journey, let's start with the Context, since from a programmer's perspective, most of the DCI-related things happen in there.

The DCI Context

A DCI Context is a structure that encapsulates system behavior, in contrast to objects and classes which encapsulate state well, but only capture fragments of the interactions between objects in the system, which makes a system more difficult to reason about as it grows.

One of the goals of DCI is to prevent the spreading of functionality across arbitrary boundaries, be it a class hierarchy, helpers, services, patterns, etc. Many programming constructs abstract away relevant information (like interfaces), or provides irrelevant information (classes), so we are left with either a limited or overwhelming view when trying to understand how the system works at runtime.

The current way of gaining an understanding of runtime system behavior is to use a debugger, or become the debugger by tracing the program in your head, branching and jumping across class hierarchies, events, exceptions, etc. Something is obviously problematic with this hope that the parts of a system will self-organize, yet every torturous visit to the debugger proves otherwise.

Fortunately, a DCI Context not only encapsulates but also describes the runtime behavior of a network of interaction objects in a relevant locus, without hiding information behind classes, interfaces and polymorphism. So how does it work?

A basic Context

A true DCI execution model is difficult to achieve today due to several technical reasons, but I've created a TypeScript library that tries to get close by making the code adhere to certain conventions. It can be installed by following the instructions at https://github.com/ciscoheat/eslint-plugin-dci-lint

If you want to follow this tutorial in code, you can do that with Stackblitz by clicking here.

The library tries to provide the simplest possible structure for a working DCI Context, within the limits of TypeScript syntax. Here's an example of a "Hello World" Context:

/**
 * @DCI-context
 * A speaker proclaims something to the world, that dutifully notes it
 */
function HelloWorld(
  Speaker: { phrase: string },
  World: { log: (msg: unknown) => void }
) {
  function Speaker_proclaim() {
    World_note(Speaker.phrase);
  }

  function World_note(phrase: string) {
    World.log(phrase);
  }

  Speaker_proclaim();
}

First, the @DCI-context tag on top is required for the library to work. It can be put in a simpler // @DCI-context comment as well, right above the function.

The Context may look a bit unusual, due to the capitalized variables and underscored methods. The underscore is a syntax limitation that will be explained later, but capitalization is only a convention. UPPERCASE has been used in other examples, similar to a movie script that uses uppercase to highlight importance, but it may be too sore on the eyes, so capitalization is a middle ground.

Looking at the Context, two often mentioned parts seem to be Speaker and World. What are they? They're not classes, since they are typed as literal objects. You don't have to look up the public interface of a class or type in a different file to understand what they can do. As said, a goal with DCI is to be able to understand the code from a different perspective - in a Context we're standing between objects, describing and observing how they interact, only being interested in what's relevant in the context, in this case, proclaiming something to the world.

This is in contrast to traditional OOP, where we are placed inside the objects, only seeing a limited view of the system (the class interface and its outgoing messages).

A brief introduction to Roles

Again, what is the Speaker and the World? The answer is that they are Roles. A Role is an identifier within a Context, with a literal type, called a RoleObjectContract, or just contract.

Like in a movie, a Role can be played by an actor - in our case an object, but just as real actors casting for a certain role, the object must adhere to certain characteristics. Here are the Roles for HelloWorld again:

/**
 * @DCI-context
 * A speaker proclaims something to the world, that dutifully notes it
 */
function HelloWorld(
  Speaker: { phrase: string },
  World: { log: (msg: unknown) => void }
)

Looking at Speaker, from its contract we discern that any object with a string property called phrase can play the Role of Speaker. Let's create a super-simple object just for that purpose:

const you = { phrase: "Hello, World!" };

The contract for the World Role is a log function that accepts anything and returns nothing. With a bit of knowledge about Javascript runtimes, we know that the global console object matches that contract.

About naming: Why are the Roles in this Context named "Speaker" and "World"? That has to do with the mental model the Context is based upon, which will be the topic of the next part. Until then, just note that the comment above the Context mentions these two names.

The Data part of DCI

The objects you and console are the Data part of the DCI acronym; simple objects with little awareness of the rest of the system, which is very well, because in DCI we don't want to mix Data (what the system is) with Functionality (what the system does). Not only do they have different rates of change, so a domain separation is already obvious, but mixing them leads to the classic issue of objects taking on more and more responsibilities, eventually resulting in an entangled and fragile jumble.

RoleMethods

Looking at the HelloWorld Context again, we see an underscored method:

function Speaker_proclaim() {
  World_note(Speaker.phrase);
}

The underscore, being a rather poor substitute for a period due to syntax limitations, demarcates a RoleMethod. Its name always starts with one of the Roles in the Context, working as an extension of the object playing the Role while it's inside the Context. See it as the object playing the Role of Speaker gets a proclaim() function attached to it when, and only when, the HelloWorld Context is executing.

The Interaction part of DCI

In the function body of Speaker_proclaim, we see that the Speaker interacts with the World Role, by calling one of its RoleMethods:

function Speaker_proclaim() {
  World_note(Speaker.phrase);
}

function World_note(phrase: string) {
  World.log(phrase);
}

In World_note, the World calls its log method, and this is a very important part of DCI - only the Role can access its contract. It solely decides when to call its underlying object, inside its own RoleMethods. This is one of several rules that the linter library is upholding. For example, this would lead to an error:

// Trying to take a shortcut:
function World_note() {
  World.log(Speaker.phrase); // Error: Call to a Role contract outside its own RoleMethods.
}

By preventing access to the underlying objects from other Roles, we gain additional security. Just as computer memory is protected by an operating system, we shouldn't be able to dive into the internals of any object in our system without consideration, and being explicit about it.

Executing the Context - System interaction

At the end of the Context, there is an entry point for its execution:

Speaker_proclaim();

This is called a System Interaction which starts a flow of interactions through the Context by calling a RoleMethod. We can do this in two different ways:

A. When the Context describes functionality that should execute "on the spot", like in this example, putting a RoleMethod at the end is a simple way of starting it. Using our objects you and console, it will look just like this:

const you = { phrase: "Hello, World!" };

HelloWorld(you, console);

B. If you instead want to reuse the context, or pass parameters to it, you can achieve a more OO approach by letting it return an object, basically the public interface of the Context:

function HelloWorld(
  Speaker: { phrase: string },
  World: { log: (msg: unknown) => void }
) {
  function Speaker_proclaim() {
    World_note(Speaker.phrase);
  }

  function World_note(phrase: string) {
    World.log(phrase);
  }

  return {
    note: () => Speaker_proclaim()
  }
}

Which will make the Context usable as an object:

const you = { phrase: "Hello, World!" };
const world = HelloWorld(you, console);

world.note();

This concludes part 1 of this DCI tutorial! The HelloWorld Context is a bit contrived, but the next part will explain why methods like Speaker.exclaim and World.note are important, instead of a simple console.log(you.phrase). Please continue in part 2.

Official website

For more information about DCI, its official website is https://fulloo.info.

In a similar vein, programmers have gone from command line-loving basement dwellers to hipster rockstars, and now back to some modern, shaped up version of the former, that loves over-engineered solutions and spending 25 hours a day delving into every single detail of the hoops you have to jump through to get something working, as well as comparing all these frameworks. And as soon as they grasp the concept, they excitingly reinvent the wheel, adding to the already bizarre amount of libraries and packages.

Unfortunately they do this without long-term thinking, as we can surely see by the amount of libraries and frameworks that ends up abandoned or decidedly "not such a good idea" by consensus, after a brief period of time.

For example, which validation library should I use? Joi, Zod, Ajv or Yup? They all look similar, do similar things, have a similar API, similar sponsors, similar documentation, and a similar list of similar companies using them. I don't want to spend my days digging through these or every other part of the project that needs a library. It's so rare that these are new problems. There should already be an effective, established general solution, and all that the library programmers would have to do is to port it to their favorite language and platform. But following a dry specification is tedious compared to the fun part of letting your imagination break the mould, so "I want to use my own ideas!" the nerd youthfully exclaims, while writing yet another HTTP client.

There's nothing wrong with that as a learning process, but what's happening in the development world is turning into navel-gazing and a waste of time and money. We code mainly for others, and others usually pay us for doing a good job in good time. Reinventing wheels is not included in that. Therefore, the nerds need a wake-up call. A way to do this could be for the package managers to have a sandbox and strict version control. This is the message you should get when you've uploaded a package:

"Thanks for your contribution! You're gonna be in this hidden section for some time, whether you're backed by Facebook or not. The only way for the public to use your library in the first year is by adding some complicated flags to their project, which should be no problem for configuration-loving nerds. Warnings will be displayed when doing that, of course. Our AI will also link your project to similar, public ones, and also to the closest related standard, with helpful suggestions how you can adhere closer to it. After a year, if you're still around and decide to publish, your API must be set to version 1.0.0+, and if you break it, you're back in the sandbox."

Who will answer to this call? I can't myself unfortunately, I'm stuck being a human API decoder and comparer of frameworks...

Poor MVC! It's probably the most misunderstood "pattern" in the history of computer science.

Why? Viewing MVC as simply separation of concerns leads to unnecessarily complicated solutions to simple problems. MVC is richer than a single pattern - it is a pattern language, created to align the computer and the programmer with the mental model of the end user.

So if you want to expand your view on a very useful and well researched pattern language, let's try to understand it again, beginning with a visit to the past.

A brief history of Patterns

70s

When Trygve Reenskaug started his research back in the 70s, great ideas were going on in computer science. No doubt computers were here to stay, and people like Alan Kay and Doug Engelbart had visions of computers being an extension of the human mind. The computer was supposed to be composed of objects, a concept that humans reasoned about naturally, and those objects were supposed to communicate with each other, essentially making the objects a recursion on the idea of the computer itself. So Trygve set out to make a connection between computer data and stuff in the end user's head, trying to make the computer think what the user was thinking.

The result, conceived in 1978, was MVC, Model-View-Controller. It was based on how humans interpret and manipulate data and information, and it seemed possible for software to take a big step towards object-orientation and user-friendliness. The computer was in grasp of any person!

80s

Then came the 80s, and the engineers were spending time with what they enjoyed, which wasn't end user mental models, dynamic interactions, user interfaces and other human-related things. No, it was structure. After some time, the actual architecture, the form of a system relevant for the users, was completely hidden by layers of abstraction called software design patterns, later known as the "GoF patterns". They were abstract, decoupled and reusable, like a house made entirely out of scaffolding. Ugly and not user friendly, but very organized, just like the engineers want it!

90s

The GoF patterns became the norm, and in the 90s the humane ideas from the 70s were mostly forgotten. Nerds ruled the computer world, and nobody else had anything to say about software design. Who could even argue? Computers were considered very complicated, no wonder when the engineers had turned the rules around. The users were basically controlled by the computer and its programmers, and most systems turned very complex (big structure) or into a mess (bad structure).

00s

In the 00s, after the dot-com bubble, the costs of this structural mess had become a real issue. This led to the idea that we shouldn't even consider architecture and planning anymore. Just be Agile! Make the structure so flexible that if any new requirements comes up, we can just add more with almost no cost. If this adding sums up to a mountain of scaffold, well, another layer of indirection/scaffold will surely solve it! Then introduce unit testing, a very[1] wasteful[2] testing method that will effectively double the code base (how Agile is that?), and not much have changed really.

But something happened around here, when the web started to grow rapidly. MVC was rediscovered as a useful pattern for websites. But alas, shoehorned into a design pattern. The idea of separation and modularity was more popular than ever, like the world was made of Lego and block modules was the best way to build a nice, lively house. Separation was enforced, and the View became an HTML container, the Controller not much more than a static class, and the model got the rest of the system, a substantial mix of data and functionality. And the debate started to rage... Fat models? Skinny models? View models? Fat Controllers? Services? Layers? Mediators? Where to put everything?

10s

No wonder people eventually got tired of this and tried to find alternative patterns and solutions (MVVM, MVP, PAC, MVA, ADR...), but blaming MVC for any of this is not fair, as you hopefully understand now. So let's move on from this history lesson and see what we can do to restore MVC to its former glory!

Correcting some misconceptions

Let's start by forgetting most of what we know about MVC from thousands of web articles. Unfortunately it's necessary, most are based on the "design pattern" view of MVC, the nerd-centric approach. If we want a way out of the above mess, we have to reconnect to the end user.

Mental models

A mental model is "an explanation of someone's thought process about how something works in the real world." This is what Reenskaug had in mind with MVC:

We have the User's mental model, where the View is a bridge between the Model and the User. The user observes the Model through the View and gives input through the View to the Model, experiencing an illusion of working directly with his or her information (the Model). This means that the Views appear to communicate directly with the Model. The illusion can only be upheld if all Views are synchronized to always show the current Model. How this is done is an implementation detail.

The fundamental idea for the programmer's mental model was to separate the computer representation of the user's mental information model (the Model) from the parts of the program that facilitate the user observing and editing selected aspects of it, the Views. Views are created and coordinated by a Controller. Any actual message flow will be acceptable as long as it upholds the user's mental model.

This is very welcome information that helps correct some misconceptions about MVC. What else can we find? In Reenskaug's human centered document MVC - Its Past and Present, it is shown how MVC works as a pattern language, and there we'll make some other discoveries:

1. Objects can be any combination of M, V and C!

In MVC - Its Past and Present on page 10-11, we find something ignored by countless programmers who have been enforcing separation at all costs:

• In simple cases, the Model, View and Controller roles may be played by the same object. Example: A scroll bar.
• The View and Controller roles may be played by the same object when they are very tightly coupled. Example: A Menu.
• In the general case, they can be played by three different objects. Example: An object-oriented design modeller.

Shocking to anyone familiar with many popular MVC web frameworks. What about reusability and modularity, the goal of any software project worth its name? We must be able to re-use as many classes and components as possible for the next project, right?

Well, in reality, how much of that is true? Are you reusing the Views? Hardly, your next web site will look quite different. The Controllers? Nope, the routes, database access, etc, are different too. The Models then? Not if you are creating them according to the knowledge and terminology of users and Domain experts, then they will be different between customers. So what is reusable really?

It seems that we're only reusing CSS and HTML frameworks (occasionally!), some general-purpose libraries, and the GoF patterns that we still hang onto, but maybe shouldn't. Those things are quite low-level. On a higher level, we want to create things (objects) relevant to the user, and they are very specific for each project. Also, striving for reusability before something is even used, smells of premature optimization.

All this means that we can couple MVC objects because they aren't on the actual level of being reusable. We should rather embrace the natural coupling to create small, efficient objects that are easy to understand, using terms based on the end user mental models. That's a step closer towards the Kay object-oriented vision for sure.

2. The View is an object!

This follows from the previous point, confirmed recently by Trygve, but it's still worth emphasizing because the "web view" idea is so dominating: A "View" in web apps is usually considered a template, a code snippet rendered to HTML and displayed in the browser. Quite simple to use, but not as dynamic as web requirements are today. In early sites the template had to be populated with data, but there was no natural place for the data since there were no objects in sight. The template engine and framework handled this with key-value mappings initially, but after a while the View Model was invented. An object containing the data required for a view template to display correctly.

This is an example of something being invented because people are more interested in innovation than building on already laid foundations. Older stuff isn't as trendy, but it is solid and useful, like a timeless piece of equipment surviving through the ages.

If we instead apply the idea that a MVC View is an object, we can pass the relevant Model directly to that object, in the constructor for example, and we don't have to invent a concept like a View Model, that doesn't make sense to the user and/or complicates the program. State not related to the Model can be put directly in the View.

That solves the data part of the View, but what about functionality? Web apps today are quite interactive, but it's contrived to model interaction in a template snippet. Again, objects are a much better fit.

If you agree that the View should be an object, finding a MVC web framework that allows us to create Views as simple objects isn't that easy. Mithril is a shining exception however. It lets one focus on the system architecture instead of structure. It uses View Models, but they aren't a requirement. Svelte is another example that embraces the natural coupling of MVC. Overall, the situation is improving with the "components" approach, which, in light of the above information, is really MVC in disguise.

More details

Those were some urgent points. Now let's get into details, focusing on web development. The following list about the responsibilities of MVC objects is taken from the excellent book Lean Architecture by James Coplien, and I've added some comments.

Model

- Updates its data at the request of commands from the Controller

This has been corrected since the book was published. Most user input comes in through the View, which will usually pass the input on to its Model, if the implementation allows. For modern web apps, objects are in memory in the browser, so it's no problem to let the View talk to the Model directly, since the View is coupled to the Model data anyway.

- Notifies appropriate Views when its state changes
- Can be asked to register/de-register Views

Progress has been made here for the web: Previously we've been stuck with tedious DOM manipulations, which made these two points seem necessary. In modern javascript frameworks like Mithril and React however, using a fast diff algorithm there is no need to register or tell specific Views that something has changed. The framework can be requested to redraw anytime, and the smallest possible DOM modification will be made. This gets rid of the Observer pattern, for example. Svelte takes it even further by compiling modifications instead of calculating them at runtime, eliminating the need for a diff algorithm.

View

- Presents a particular representation of the data to the user
- Can ask a Model for the current value of data it presents to the user

This is quite simple now that we have a View object that either is passed a Model, or is the model itself. Just ask the Model for the data and display it appropriately.

Regarding the relationship between Models and Views, Reenskaug and Coplien agrees that "a given view canonically has a single Model." Reenskaug continues:

Other Views can have other Models. The subview structure could reflect the model structure, or it may merely keep things together that belong together in the user's tasks.

- Can handle its own input

In web applications, the View object is usually the point of user interaction, through DOM events. Quoting Coplien here:

A View can handle some of its own input (e.g., a text input field can handle all local text processing - backspaces, line kills, etc.) only to send the data to the Model when an ENTER key is pressed or a button is pushed - but that's kind of an optimization. The important is that the end users should feel as though they are interacting directly with the Model. That completes the link from the end user mind to the program and back.

Many modern frameworks uses DOM events to automatically redraw the screen, since most user input results in some visual change. Again very useful to avoid patterns like Observer.

- Together with the Controller, handles selection

This one is interesting. From MVC - Its Past and Present, page 13:

A user selects one or more objects in one of the Views. The selection should appear in all Views where the selected object is visible in order to maintain the object model illusion. [...] Solution: Let the selection be the responsibility of an object that knows all the relevant Views.

The object in question is the Controller. This means that the Controller will contain a list available to the Views it manages. When the list changes, so will the Views displaying the selected objects. The selection input is passed on from the Views to the Controller.

Controller

In the original MVC, a Controller is mainly a View manager, with the following responsibilities:

- Creates and manages Views

When Views are objects, a common issue of how to organize "parent-child" or "between component" communication is much simplified. The Controller will instantiate the required views and make sure the correct Models are passed to them. An illuminating note from Reenskaug:

Let a View play two roles: Let it be managed by its Controller in the usual manner and, at the same time, be (sub)Controller that manages a number of subviews.

- Handles selection across Views

See the last point in the View section above.

- Passes commands to the Model

This has also been corrected as of late. Since the Views talks directly to the Model when possible, it's not required to pass any commands through the Controller. It could be required if the Controller is the only way in the framework to send requests to the server, but that's also an implementation detail.

Commands are further discussed in The original MVC reports:

A view should never know about user input, such as mouse operations and keystrokes. It should always be possible to write a method in a controller that sends messages to views which exactly reproduce any sequence of user commands.

This has been confirmed by Reenskaug as implementation-specific, not a general rule. But even though the View can handle input in the browser, the last part is still a useful guideline when writing the public interface/API for the MVC objects. Do they reflect the way the user thinks about the system? And when someone wants to connect to your useful software with other software, will it be an intuitive process, or will it feel like a feature that was slapped on as an afterthought?

- Handles commands that applies to the entire window

Having an overarching Controller for the whole window already exists in many MVC frameworks. It's usually called a Router, and now when we allow it to be any combination of M, V and C, its usefulness increases.

The User

I hope you can now see and better understand the composition of a system using MVC. Objects are playing the roles of M, V and C, containing other objects that exists and communicates according to the mental model of the User. To signify how important the last part is, Reenskaug and Coplien have improved the name of the pattern to MVC-U, finally including the User, the most important part of the system. It is, after all, not only for ourselves but mostly for others we code.

DCI - The MVC complement

If you want to dive even deeper in system architecture: In languages today there isn't a natural place for functionality that involves a network of communicating objects. This is a topic that leads us to DCI (Data, Context, Interaction), Reenskaug's next invention, co-authored by Coplien.

It is a new paradigm in system architecture, designed as a complement to MVC. Quoting from the introductory article The DCI Architecture:

The MVC framework makes it possible for the user to reason about what the system is: the thinking part of the user cognitive model. But there is little in object orientation, and really nothing in MVC, that helps the developer capture doing in the code. The developer doesn't have a place where he or she can look to reason about end user behavioral requirements.

As with any new paradigm, it cannot be understood with help of the previous one, so it takes some effort, but is really worth the time. It will make you a better programmer, guaranteed. The official DCI webpage at http://fulloo.info/ is simple but informative, has a thorough FAQ, and as I've spent 10 years on the DCI frontier, I'm also available for answering your questions. Enjoy!

A final note

Reenskaug writes in a mail:

It is important to realize that these reports reflect an idea and a particular implementation. They are not a final answer where every sentence can be taken as normative.

A humble acknowledgement that things will be different in various systems, and in the future. If we strive towards simplicity and focus on the end user, the above ideas should in any case get us closer to a better way to write useful software, I'm quite certain of that!

Now when you know more about the human side of MVC, I hope it will become a great help in your future system design. Thanks for reading, and please let me know what you think!