Published Dossier API – getEntity

getEntity is used to get a published entity. You can reference the entity by id or by a unique index reference.

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

interface EntityReference {
  id: string;
}

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

▶️ Get entity by id

This example shows how to get a published entity by specifying the id. Please note that we use publishedClient to get the entity.

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

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

▶️ Get entity by unique index

This example shows how to get a published 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" },
  },
  { publish: true },
);
createResult.throwIfError();

const getResult = await publishedClient.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 Published Dossier Exception Client to make the API call.

The normal Published 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 publishedExceptionClient = publishedClient.toExceptionClient();

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

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

try {
  await publishedExceptionClient.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 publishedClient = server.createPublishedDossierClient(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();