AbsoluteJS

Artifacts

@absolutejs/artifactsv0.1.3betaAI

Typed, versioned artifacts for AI products — schemas, lifecycle, storage, rendering, publishing, revisions, and agent tools without prescribing a database or host.

#Installation

BASH
bun add @absolutejs/artifacts

#Capabilities

Overview

The typed lifecycle for things an AI makes.

An AI-generated page, report, plan, email, deck, or image should not disappear into a chat transcript or become an unvalidated blob. It should have a kind, structured content, ownership, provenance, revisions, capabilities, renderers, and an explicit publication lifecycle.

@absolutejs/artifacts provides those contracts without owning your database, routes, authorization, UI, or hosting.

What it owns

Structured artifact-kind schemas and runtime validation

Draft, published, and archived lifecycle states

Immutable revision history, restoration, and optimistic updates

Show 10 more

Structured content plus opaque references to generated or source files

Artifact, asset, renderer, and publisher storage interfaces

In-memory artifact and asset stores for development and tests

Owner-bound lifecycle tools structurally compatible with AI tool maps

Provenance fields for model, tool, trace, and source entities

Standard file-backed kinds for documents, presentations, spreadsheets,

datasets, code, images, audio, video, email, archives, and generic files

An optional bridge to @absolutejs/rag ingestion

Provider-neutral generation registries with atomic multi-file bundles

Revision-pinned or explicitly live publications

Define kinds once

Every successful create or lifecycle mutation appends an immutable snapshot. Restoring history creates a new private draft instead of rewriting or republishing an old revision:

Production persistence

Use the package-owned Drizzle schema on PostgreSQL, including Neon. The store atomically writes the current artifact, immutable revision, and lifecycle outbox events. It also persists per-revision indexing state and fences every artifact read and mutation by owner.

Export artifactDrizzleSchema from your application's Drizzle schema so its normal migration workflow owns the four tables. Insert and select TypeBoxes generated directly from those tables are exported from the same entry point; hosts should reuse them instead of redefining database row schemas.

When a host owner is permanently deleted, call artifacts.purgeOwner(ownerId). The production store removes its current records, revisions, indexing state, and outbox events in one transaction; orphaned asset bytes remain subject to the package's history-aware garbage collector.

File-backed artifact kinds

Use the bundled definitions directly or compose them with application-specific kinds:

File bytes stay in host storage. Artifact records retain opaque references with name, media type, size, checksum, role, and storage URI. The URI is not treated as a public URL and the package reads it only through the configured asset store. Detaching a file does not delete its bytes because older immutable revisions may still reference it.

Multiple generated files should use one staged transaction and therefore one artifact revision:

Generation

Generators are provider-neutral. They return validated structured content and zero or more file writes; the registry commits those outputs through the same artifact bundle lifecycle:

RAG ingestion

The optional @absolutejs/artifacts/rag entry point resolves one current or historical artifact record into the upload contract already accepted by @absolutejs/rag. Structured content is included as JSON and every attached file is included without exposing its storage URI:

createArtifactRAGIndexCoordinator wraps that conversion with durable pending, indexed, and failed state. It removes document IDs from the previous indexed revision after the replacement succeeds.

Events and retention

Every lifecycle mutation supplies its event to the artifact store in the same call that writes the current record and immutable revision. Durable adapters should commit those rows in one database transaction, then workers can consume unprocessed events for RAG indexing, previews, notifications, scanning, or conversion.

Asset collection compares storage candidates with references across every retained revision. collectAssetGarbage({ dryRun: true }) previews deletion; only unreferenced objects older than the configured minimum age are eligible.

Compose publishing and rendering

Publishing is an adapter because public access is a host policy:

Publishing defaults to pinned: the public record names the exact immutable revision. mode: "live" is an explicit alternative whose revision advances with later edits.

Renderers are independently registered by artifact kind and output format:

Show 1 more

The package never treats generated HTML or JavaScript as trusted executable content. Applications should define structured content schemas and render them through controlled adapters.

AI tools

createArtifactTools binds create, list, get, update, publish, and unpublish operations to one owner. The returned definitions use TypeBox inputs and the same { description, input, handler } shape used by @absolutejs/ai.

Only expose the publication tool where the user explicitly controls public access.

Outcomes

What you can build

Overview

The typed lifecycle for things an AI makes.

What it owns

Structured artifact-kind schemas and runtime validation

Define kinds once

Every successful create or lifecycle mutation appends an immutable snapshot. Restoring history creates a new private draft instead of rewriting or republishing an old revision:

Hardening checklist

Production guidance

Production persistenceUse the package-owned Drizzle schema on PostgreSQL, including Neon. The store atomically writes the current artifact, immutable revision, and lifecycle outbox events. It also persists per-revision indexing state and fences every artifact read and mutation by owner.
Events and retentionEvery lifecycle mutation supplies its event to the artifact store in the same call that writes the current record and immutable revision. Durable adapters should commit those rows in one database transaction, then workers can consume unprocessed events for RAG indexing, previews, notifications, scanning, or conversion.
AI toolscreateArtifactTools binds create, list, get, update, publish, and unpublish operations to one owner. The returned definitions use TypeBox inputs and the same { description, input, handler } shape used by @absolutejs/ai.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/artifacts example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#Production persistence

Partial snippet

Use the package-owned Drizzle schema on PostgreSQL, including Neon. The store atomically writes the current artifact, immutable revision, and lifecycle outbox events. It also persists per-revision indexing state and fences every artifact read and mutation by owner.

TS
import {
  artifactDrizzleSchema,
  createDrizzleArtifactStore,
} from "@absolutejs/artifacts/drizzle";

const store = createDrizzleArtifactStore({ db });

#Define kinds once

Partial snippet

Working example for Define kinds once.

TS
import { Type } from "@sinclair/typebox";
import {
  createArtifactService,
  createMemoryArtifactAssetStore,
  createMemoryArtifactStore,
  defineArtifactRegistry,
} from "@absolutejs/artifacts";

const registry = defineArtifactRegistry({
  page: {
    capabilities: ["archive", "edit", "preview", "publish"],
    content: Type.Object({
      blocks: Type.Array(
        Type.Union([
          Type.Object({ heading: Type.String(), type: Type.Literal("hero") }),
          Type.Object({ body: Type.String(), type: Type.Literal("text") }),
        ]),
      ),
      theme: Type.Union([Type.Literal("dark"), Type.Literal("light")]),
    }),
    label: "Page",
    schemaVersion: 1,
  },
});

const artifacts = createArtifactService({
  assetStore: createMemoryArtifactAssetStore(),
  registry,
  store: createMemoryArtifactStore(),
});

const page = await artifacts.create("owner-123", {
  content: {
    blocks: [{ heading: "A real page", type: "hero" }],
    theme: "light",
  },
  createdBy: "agent",
  kind: "page",
  provenance: { model: "your-model", tool: "create_page" },
  title: "Launch page",
});

#Define kinds once 2

Partial snippet

Every successful create or lifecycle mutation appends an immutable snapshot. Restoring history creates a new private draft instead of rewriting or republishing an old revision:

TS
const history = await artifacts.listRevisions("owner-123", page.id);
const restored = await artifacts.restore("owner-123", page.id, 1);

#Public entry points

Supported entry points declared by this project’s package manifest. Internal dist paths are not part of the package contract.

Public package entry point declared in package.json.

@absolutejs/artifacts@absolutejs/artifacts/manifest@absolutejs/artifacts/manifest.json@absolutejs/artifacts/drizzle@absolutejs/artifacts/rag

#Package commands

Scripts declared by this project’s package manifest.

bun run buildrm -rf dist && bun build src/index.ts src/drizzle.ts src/manifest.ts src/rag.ts --outdir dist --root ./src --target=bun --external @absolutejs/rag --external @sinclair/typebox --external @sinclair/typebox/value --external drizzle-orm --external 'drizzle-orm/*' --external drizzle-typebox && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit
bun run formatprettier --write "./**/*.{ts,json,md}"
bun run testbun test
bun run typechecktsc --noEmit --project tsconfig.json

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

58 symbols
defineArtifactRegistryexportPermalink
TS
defineArtifactRegistry
Exported from @absolutejs/artifacts