Dossier API – getEntity

getEntity is used to get an entity. You can reference the entity by id or by a unique index reference. When referencing the entity by id, it's possible to fetch a specific version of the entity.

interface DossierClient {
  getEntity(
    reference: EntityReference | EntityVersionReference | UniqueIndexReference,
  ): PromiseResult<
    Entity,
    "BadRequest" | "NotFound" | "NotAuthorized" | "Generic"
  >;
}

interface EntityReference {
  id: string;
}

interface EntityVersionReference {
  id: string;
  version: number;
}

interface UniqueIndexReference {
  index: string;
  value: string;
}

▶️ Get entity by id

This example shows how to get the latest version of an entity by specifying the id.

// First, create an entity
const createResult = await client.createEntity({
  info: { type: "Message" },
  fields: { text: "Hello world" },
});
const {
  entity: { id },
} = createResult.valueOrThrow();

// Get the entity by specifying the id
const getResult = await client.getEntity({ id });
console.log(
  getResult.isOk() ? JSON.stringify(getResult.value, null, 2) : getResult,
);

▶️ Get specific version of entity

This example shows how to get a specific version of an entity. First we create and update an entity to create two versions. Then we get the first version.

const createResult = await client.createEntity({
  info: { type: "Message" },
  fields: { text: "First version" },
});
const {
  entity: {
    id,
    info: { version: firstVersion },
  },
} = createResult.valueOrThrow();
console.log(`Created entity with id: ${id} (version: ${firstVersion})`);

const updateResult = await client.updateEntity({
  id,
  fields: { text: "Second version" },
});
const {
  entity: {
    info: { version: secondVersion },
  },
} = updateResult.valueOrThrow();
console.log(`Updated entity with id: ${id} to version ${secondVersion}`);

// Get first version
const getResult = await client.getEntity({ id, version: 1 });
console.log(
  getResult.isOk() ? JSON.stringify(getResult.value, null, 2) : getResult,
);

▶️ Get entity by unique index

This example shows how to get an entity by a specific value of a unique index. As you can see at the bottom of this page where we initialize the schema, we have created a unique index on the slug field.

const createResult = await client.createEntity({
  info: { type: "Message" },
  fields: { text: "Hello world", slug: "hello-world" },
});
createResult.throwIfError();

const getResult = await client.getEntity({
  index: "slugIndex",
  value: "hello-world",
});
console.log(
  getResult.isOk() ? JSON.stringify(getResult.value, null, 2) : getResult,
);

▶️ Using the exception client

This example shows how to use the Dossier Exception Client to make the API call.

The normal Dossier Client returns a PromiseResult for all operations. Even if the API call fails, no exceptions are thrown. The benefit is that you are forced to handle errors for all calls and TypeScript helps you in knowing which errors can occur. However, sometimes it can be easier to use exceptions.

const exceptionClient = client.toExceptionClient();

const {
  entity: { id },
} = await exceptionClient.createEntity({
  info: { type: "Message" },
  fields: { text: "Hello" },
});
console.log(`Created entity: ${id}`);

const entity = await exceptionClient.getEntity({ id });
console.log("Got entity", JSON.stringify(entity, null, 2));

try {
  await exceptionClient.getEntity({ id: "missing" });
} catch (error) {
  console.error("Failed to get entity", error);
}

Initialization of Dossier for this page

This code used to set up Dossier for the examples on this page. The examples are run entirely in the browser.

const dossierCore = await import("https://esm.sh/@dossierhq/core@0.7.6");
const dossierServer = await import("https://esm.sh/@dossierhq/server@0.7.6");
const dossierSqlJs = await import("https://esm.sh/@dossierhq/sql.js@0.7.6");
const { default: initSqlJs } = await import("https://esm.sh/sql.js@1.10.3");

const logger = dossierCore.NoOpLogger;

const SQL = await initSqlJs({
  locateFile: (file) => `https://sql.js.org/dist/${file}`,
});
const database = new SQL.Database();
const databaseAdapterResult = await dossierSqlJs.createSqlJsAdapter(
  { logger },
  database,
  {
    migrate: true,
    fts: { version: "fts4" },
    journalMode: "memory",
  },
);
const databaseAdapter = databaseAdapterResult.valueOrThrow();

const serverResult = await dossierServer.createServer({ databaseAdapter });
const server = serverResult.valueOrThrow();

const sessionResult = await server.createSession({
  provider: "sys",
  identifier: "user",
});
const session = sessionResult.valueOrThrow();
const client = server.createDossierClient(session.context);

const schemaResult = await client.updateSchemaSpecification({
  entityTypes: [
    {
      name: "Message",
      nameField: "text",
      fields: [
        { name: "text", type: "String" },
        { name: "slug", type: "String", index: "slugIndex" },
      ],
    },
  ],
  indexes: [{ name: "slugIndex", type: "unique" }],
});
schemaResult.throwIfError();