Class Translator<DT, AT>

Translators perform the work of translating data between database format and api format^[1]. They are instantiated with an api prefix (e.g., '/registry/v3', '/brokerage/v2', etc...), a default type, a spec, and an optional tranform function^[2]. It is intended that each service will maintain a library of resource translators that can be used throughout the service.

Example

export const User = new Translator(
  "/users/v1",
  "users",
  {
    fullName: "attr",
    birthdate: "attr",
    active: "attr",
    bestFriend: [ "bestFriendId", "users" ],
  },
  (from: "db"|"api", k: string, v: unknown) => {
    // We happen to know that "active" is boolean, which is stored in the database as an int.
    // If coming from the db, we need to make the value boolean, and if coming from the api, we
    // need to make it numeric.
    if (k === "active") {
      return from === "db"
        ? !!Number(v)
        : Number(v);
    }

    // We also know that dates are in the database as a date string, but we want to pass them
    // as an integer (timestamp in MS)
    } else if (k === "birthdate") {
      return from === "db"
        ? new Date(v).getTime()
        : new Date(v).toISOString()
    }

    // For any other fields, we just want to pass them back as-is
    return v;
  }
)

User.dbToApi({
  id: "aaaabbbbcccc-dddd-eeee-ffff-0000111122223333",
  fullName: "Mr. Katz",
  birthdate: "2000-01-01T00:08:00.00-00:00",
  active: 1,
  bestFriendId: "000011112222-3333-4444-5555-6666777788889999"
});

// Yields
// {
//   id: "aaaabbbbcccc-dddd-eeee-ffff-0000111122223333",
//   fullName: "Mr. Katz",
//   birthdate: 946685280000,
//   active: true,
//   bestFriend: { data: { type: "users", id: "000011112222-3333-4444-5555-6666777788889999" } }
// }

User.apiToDb({
  id: "aaaabbbbcccc-dddd-eeee-ffff-0000111122223333",
  fullName: "Mr. Katz",
  birthdate: 946685280000,
  active: true,
  bestFriend: { data: { type: "users", id: "000011112222-3333-4444-5555-6666777788889999" } }
});

// Yields
// {
//   id: "aaaabbbbcccc-dddd-eeee-ffff-0000111122223333",
//   fullName: "Mr. Katz",
//   birthdate: "2000-01-01T00:08:00.00-00:00",
//   active: 1,
//   bestFriendId: "000011112222-3333-4444-5555-6666777788889999"
// }
Copy

Footnotes

• [1] Unfortunately, these functions cannot be purely type safe because API formats are not necessarily directly related to DB formats (i.e., there is not a one-to-one relationship between key-value pairs in the DB format and key-value pairs in the API format). Thus, the best we can do is provide the intended DB type and the intended API type and then an additional function (transform, see below) that serves to transform attribute data between database and api formats. Because of this, it is imperitive that you double-check the output of your Translators using unit tests.
• [2] The transform param allows you to transform values between api and db format. For example, you may store boolean values as TINYINT in the database, or uuid values as BINARY(16) in the database. You can use the transform function to perform these transformations in each direction.