bunsane 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to bunsane are documented here.
 
+## 0.5.2 — 2026-06-19
+
+### Added
+
+- **`withLock(key, fn, options?)`** — public distributed-lock primitive,
+  exported from `bunsane/core`. Runs `fn` while holding a PostgreSQL advisory
+  lock and always releases it (even if `fn` throws); only one holder of a given
+  `key` runs `fn` at a time across every process pointed at the same database.
+  Returns `{ acquired: true, result }`, or `{ acquired: false }` when the lock
+  is held elsewhere (`fn` does not run). Wraps the same `DistributedLock`
+  singleton and PostgreSQL session the scheduler uses for task exclusion, now
+  surfaced for app-level "run once cluster-wide" work — reindex, migration,
+  cache rebuild. `options.wait` (ms, default `0` = try once) blocks for the lock
+  instead of skipping; `options.retryInterval` (default 100 ms) sets the poll
+  cadence. Layers an in-process guard over the advisory lock because PostgreSQL
+  advisory locks are reentrant per session — without it, two concurrent
+  same-key callers in one process would both win. Not reentrant; crash-safe
+  (session-scoped); honors `distributedLocking: false` (then always reports
+  `acquired: true` with no real lock). Also re-exported from
+  `bunsane/core/scheduler`. A new `core/index.ts` barrel establishes
+  `bunsane/core` as a public entry point.
+
 ## 0.5.1 — 2026-06-16
 
 ### Added

package/core/ArcheType.ts

@@ -1035,7 +1035,7 @@ export class BaseArcheType {
 
     public buildFilterBranches(filter?: FilterSchema<any>): any[] {
         if (!filter) return [];
-        const branches = [];
+        const branches: Array<{ component: any; filters: Array<{ field: string; operator: any; value: any }> }> = [];
 
         for (const [fieldName, componentCtor] of Object.entries(this.componentMap)) {
             const fieldOption = this.fieldOptions[fieldName];

package/core/app/metricsCollector.ts

@@ -2,11 +2,12 @@ import { logger as MainLogger } from "../Logger";
 import { SchedulerManager } from "../SchedulerManager";
 import { preparedStatementCache } from "../../database/PreparedStatementCache";
 import { getDbStats } from "../../database/instrumentedDb";
+import type { CacheManager } from "../cache/CacheManager";
 
 const logger = MainLogger.child({ scope: "App" });
 
 export async function collectMetrics(app: any) {
-    let cacheStats = null;
+    let cacheStats: Awaited<ReturnType<CacheManager["getStats"]>> | null = null;
     try {
         const { CacheManager } = await import('../cache/CacheManager');
         cacheStats = await CacheManager.getInstance().getStats();

package/core/app/requestRouter.ts

@@ -198,16 +198,45 @@ export async function handleRequest(app: any, req: Request): Promise<Response> {
 
         for (const [route, folder] of app.staticAssets) {
             if (url.pathname.startsWith(route)) {
-                const relativePath = url.pathname.slice(route.length);
-                const filePath = path.join(folder, relativePath);
+                const rawRelative = url.pathname.slice(route.length);
+                // Decode percent-encoding first so encoded traversal sequences
+                // (e.g. %2e%2e%2f) can't slip past the containment check.
+                let decodedRelative: string;
                 try {
-                    const file = Bun.file(filePath);
+                    decodedRelative = decodeURIComponent(rawRelative);
+                } catch {
+                    clearTimeout(timeoutId);
+                    return wrap(new Response("Bad request", {
+                        status: 400,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+                // Resolve absolutely and confirm the target stays inside the
+                // served folder — blocks path traversal (../) out of the dir.
+                // Strip leading slashes so path.resolve treats the request as
+                // relative to the folder (an absolute-looking arg would reset
+                // to the filesystem root and bypass containment).
+                const relForResolve = decodedRelative.replace(/^[/\\]+/, "");
+                const resolvedBase = path.resolve(folder);
+                const resolvedFile = path.resolve(resolvedBase, relForResolve);
+                if (
+                    resolvedFile !== resolvedBase &&
+                    !resolvedFile.startsWith(resolvedBase + path.sep)
+                ) {
+                    clearTimeout(timeoutId);
+                    return wrap(new Response("Forbidden", {
+                        status: 403,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+                try {
+                    const file = Bun.file(resolvedFile);
                     if (await file.exists()) {
                         clearTimeout(timeoutId);
                         return wrap(new Response(file));
                     }
                 } catch (error) {
-                    logger.error(`Error serving static file ${filePath}:`, error as any);
+                    logger.error(`Error serving static file ${resolvedFile}:`, error as any);
                 }
             }
         }

package/core/app/studioRouter.ts

@@ -20,6 +20,20 @@ export async function routeStudio(
         return await studioEndpoint.handleStudioComponentsRequest();
     }
 
+    if (url.pathname === "/studio/api/entities") {
+        const limit = url.searchParams.get("limit");
+        const offset = url.searchParams.get("offset");
+        const search = url.searchParams.get("search");
+        const includeDeleted = url.searchParams.get("include_deleted");
+
+        return await studioEndpoint.handleEntityListRequest({
+            limit: limit ? parseInt(limit, 10) : undefined,
+            offset: offset ? parseInt(offset, 10) : undefined,
+            search: search ?? undefined,
+            include_deleted: includeDeleted === "true",
+        });
+    }
+
     if (url.pathname === "/studio/api/query" && method === "POST") {
         const body = await req.json();
         return await studioEndpoint.handleStudioQueryRequest(body);

package/core/archetype/zodSchemaBuilder.ts

@@ -521,7 +521,12 @@ export function buildZodObjectSchema(
         graphqlSchema: graphqlSchemaString,
     });
 
-    allArchetypeZodObjects.set(nameFromStorage, r);
+    // Only cache the canonical full variant in the shared map. Function-less /
+    // relation-less variants (e.g. from getInputSchema) must not overwrite it,
+    // or weaveAllArchetypes welds SDL missing @ArcheTypeFunction fields → resolver/schema mismatch.
+    if (!excludeRelations && !excludeFunctions) {
+        allArchetypeZodObjects.set(nameFromStorage, r);
+    }
 
     return r;
 }

package/core/entity/saveEntity.ts

@@ -226,8 +226,8 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
         }
 
         // Batch inserts and updates for better performance
-        const componentsToInsert = [];
-        const componentsToUpdate = [];
+        const componentsToInsert: Array<{ id: string; entity_id: string; name: string; type_id: string; data: Record<string, any> }> = [];
+        const componentsToUpdate: Array<{ id: string; entity_id: string; name: string; type_id: string; data: Record<string, any> }> = [];
 
         for (const comp of entity.components.values()) {
             const compName = comp.constructor.name;

package/core/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Public `bunsane/core` entry point.
+ *
+ * Subpath imports (`bunsane/core/App`, `bunsane/core/middleware`, …) remain the
+ * primary surface; this barrel re-exports cross-cutting primitives intended to
+ * be imported as `bunsane/core`.
+ */
+
+export {
+    withLock,
+    type WithLockOptions,
+    type LockOutcome,
+    DistributedLock,
+    getDistributedLock,
+    resetDistributedLock,
+    DEFAULT_LOCK_CONFIG,
+    type DistributedLockConfig,
+    type LockResult,
+} from "./scheduler";

package/core/metadata/metadata-storage.ts

@@ -4,9 +4,16 @@ import type {
     ComponentPropertyMetadata,
     IndexedFieldMetadata
  } from "./definitions/Component";
-import type { ArcheTypeMetadata, ArcheTypeFieldOptions } from './definitions/ArcheType';
+import type { ArcheTypeMetadata, ArcheTypeFieldOptions, ArcheTypeFunctionMetadata } from './definitions/ArcheType';
 import type { RelationOptions } from '../ArcheType';
 
+// Mirror of decorators.archetypeFunctionsSymbol — referenced via the global symbol
+// registry to avoid a circular import between metadata-storage and archetype/decorators.
+const archetypeFunctionsSymbol = Symbol.for("bunsane:archetypeFunctions");
+
+type ArcheTypeFunctionOptions = ArcheTypeFunctionMetadata["options"];
+type ArcheTypeFunctionHandler = (entity: any, ...args: any[]) => any;
+
 function generateTypeId(name: string): string {
   return createHash('sha256').update(name).digest('hex');
 }
@@ -87,6 +94,57 @@ export class MetadataStorage {
         this.archetypes_relations_map.get(archetype_id)!.push({fieldName, relatedArcheType, relationType, options, type});
     }
 
+    /**
+     * Register a computed (@ArcheTypeFunction-equivalent) field at runtime, with no decorator.
+     *
+     * Wires all three sites the decorator path touches in one call:
+     *  - prototype symbol array → instances pick it up via `this.functions`
+     *  - prototype method → resolver invokes `archetype[propertyKey](entity, ...)`
+     *  - archetype metadata.functions → weaver emits the field in the SDL
+     *
+     * The archetype must already be registered (via @ArcheType or runtime registration)
+     * so its target class is known; throws otherwise.
+     */
+    collectArchetypeFunction(
+        name: string,
+        propertyKey: string,
+        handler: ArcheTypeFunctionHandler,
+        options?: ArcheTypeFunctionOptions
+    ) {
+        const metadata = this.archetypes.find(a => a.name === name);
+        if (!metadata) {
+            throw new Error(`Cannot register function '${propertyKey}': archetype '${name}' is not registered`);
+        }
+
+        const prototype = (metadata.target as any).prototype;
+
+        // 1. prototype symbol array (consumed by BaseArcheType ctor → this.functions)
+        if (!prototype[archetypeFunctionsSymbol]) {
+            prototype[archetypeFunctionsSymbol] = [];
+        }
+        const protoFns: ArcheTypeFunctionMetadata[] = prototype[archetypeFunctionsSymbol];
+        const protoIdx = protoFns.findIndex(f => f.propertyKey === propertyKey);
+        if (protoIdx !== -1) {
+            protoFns[protoIdx] = { propertyKey, options };
+        } else {
+            protoFns.push({ propertyKey, options });
+        }
+
+        // 2. prototype method (invoked by the field resolver)
+        prototype[propertyKey] = handler;
+
+        // 3. metadata.functions (read by the weaver to build SDL)
+        if (!metadata.functions) {
+            metadata.functions = [];
+        }
+        const metaIdx = metadata.functions.findIndex(f => f.propertyKey === propertyKey);
+        if (metaIdx !== -1) {
+            metadata.functions[metaIdx] = { propertyKey, options };
+        } else {
+            metadata.functions.push({ propertyKey, options });
+        }
+    }
+
     collectArcheTypeMetadata(metadata: ArcheTypeMetadata) {
         // Check if archetype already exists and update it
         const existingIndex = this.archetypes.findIndex(

package/core/scheduler/index.ts

@@ -13,3 +13,9 @@ export {
     type DistributedLockConfig,
     type LockResult,
 } from './DistributedLock';
+
+export {
+    withLock,
+    type WithLockOptions,
+    type LockOutcome,
+} from './withLock';

package/core/scheduler/withLock.ts

@@ -0,0 +1,98 @@
+/**
+ * withLock — run a function while holding a PostgreSQL advisory lock.
+ *
+ * Thin convenience wrapper over the shared {@link DistributedLock} singleton.
+ * Acquires the lock for `key`, runs `fn`, and always releases it — even if
+ * `fn` throws. Only one holder of a given `key` runs `fn` at a time, across
+ * every process pointed at the same database. When the lock is unavailable the
+ * call returns `{ acquired: false }` without running `fn` (unless `wait` is
+ * set, in which case it polls until the lock frees or the deadline passes).
+ *
+ * Two layers of exclusion:
+ *  - Across processes: PostgreSQL `pg_advisory_lock`, owned by the singleton's
+ *    pinned connection (one PG session per instance).
+ *  - Within a process: an in-memory `Set`. PostgreSQL advisory locks are
+ *    *reentrant per session*, so two concurrent callers sharing this instance's
+ *    session would both win the pg lock — the Set makes same-process contention
+ *    exclusive too.
+ *
+ * Notes:
+ *  - Not reentrant. Calling `withLock(key, …)` for a key already held by this
+ *    process returns `{ acquired: false }` (or waits, then gives up).
+ *  - Shares the scheduler's singleton + PG session. Keys live under the same
+ *    namespace prefix as scheduler task ids — pick keys unlikely to collide.
+ *  - Honors the singleton's `enabled` config: if distributed locking was
+ *    disabled (`getDistributedLock({ enabled: false })`), `tryAcquire` always
+ *    reports success and no real lock is taken.
+ *
+ * @example
+ * const res = await withLock("rebuild-search-index", async () => {
+ *   await rebuildIndex();
+ *   return "done";
+ * });
+ * if (!res.acquired) {
+ *   // another instance is already rebuilding — skip
+ * } else {
+ *   console.log(res.result); // "done"
+ * }
+ */
+import { getDistributedLock } from "./DistributedLock";
+
+export interface WithLockOptions {
+    /** Max ms to wait for the lock before giving up. 0 (default) = try once. */
+    wait?: number;
+    /** Poll interval while waiting, in ms. Default 100. */
+    retryInterval?: number;
+}
+
+export type LockOutcome<T> =
+    | { acquired: false; result?: undefined }
+    | { acquired: true; result: T };
+
+/** In-process holders, keyed by lock key (see "Within a process" above). */
+const localHeld = new Set<string>();
+
+const sleep = (ms: number): Promise<void> =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function withLock<T>(
+    key: string,
+    fn: () => Promise<T> | T,
+    options: WithLockOptions = {}
+): Promise<LockOutcome<T>> {
+    const { wait = 0, retryInterval = 100 } = options;
+    const deadline = wait > 0 ? Date.now() + wait : 0;
+
+    // In-process gate. The has-check that exits the loop and the subsequent
+    // add() run without an await between them, so this is atomic on JS's single
+    // thread — concurrent same-key callers cannot both pass.
+    while (localHeld.has(key)) {
+        if (!deadline || Date.now() >= deadline) {
+            return { acquired: false };
+        }
+        await sleep(retryInterval);
+    }
+    localHeld.add(key);
+
+    try {
+        const lock = getDistributedLock();
+
+        let acquired = (await lock.tryAcquire(key)).acquired;
+        while (!acquired && deadline && Date.now() < deadline) {
+            await sleep(retryInterval);
+            acquired = (await lock.tryAcquire(key)).acquired;
+        }
+
+        if (!acquired) {
+            return { acquired: false };
+        }
+
+        try {
+            return { acquired: true, result: await fn() };
+        } finally {
+            await lock.release(key);
+        }
+    } finally {
+        localHeld.delete(key);
+    }
+}

package/database/DatabaseHelper.ts

@@ -77,6 +77,41 @@ export const PrepareDatabase = async () => {
     // `entity_components` is no longer created or written. `components`
     // (UNIQUE(entity_id, type_id)) is the single source of membership truth
     // as of Phase 3 of docs/ENTITY_COMPONENTS_REMOVAL_PLAN.md.
+    try {
+        await MigrateTimestampsToTimestamptz();
+    } catch (error) {
+        logger.error(`Failed to migrate timestamp columns to timestamptz: ${error}`);
+        throw error;
+    }
+}
+
+/**
+ * Auto-migrate base-table timestamp columns from `timestamp without time zone`
+ * to `timestamptz`. Idempotent: only ALTERs columns still typed as bare
+ * timestamp, so fresh DBs (created with TIMESTAMPTZ DDL) and already-migrated
+ * DBs are no-ops. Existing bare-timestamp values are interpreted as UTC — the
+ * framework only ever writes them via NOW()/CURRENT_TIMESTAMP, which assume the
+ * DB session timezone; UTC is the correct assumption for any DB run in UTC.
+ * `components` is partitioned — PostgreSQL propagates the type change to every
+ * partition (a rewrite that briefly locks the table; one-time cost).
+ */
+export const MigrateTimestampsToTimestamptz = async () => {
+    const targets: Array<{ table: string; columns: string[] }> = [
+        { table: "entities", columns: ["created_at", "updated_at", "deleted_at"] },
+        { table: "components", columns: ["created_at", "updated_at", "deleted_at"] },
+    ];
+    for (const { table, columns } of targets) {
+        for (const col of columns) {
+            const rows = await db.unsafe(`
+                SELECT data_type FROM information_schema.columns
+                WHERE table_schema = 'public' AND table_name = '${table}' AND column_name = '${col}'
+            `);
+            if (rows.length === 0) continue; // table or column absent
+            if ((rows[0] as any).data_type !== "timestamp without time zone") continue; // already timestamptz
+            logger.warn(`Migrating ${table}.${col} timestamp → timestamptz (assuming stored values are UTC)...`);
+            await db.unsafe(`ALTER TABLE ${table} ALTER COLUMN ${col} TYPE timestamptz USING ${col} AT TIME ZONE 'UTC'`);
+        }
+    }
 }
 
 export const GetDatabaseDataSize = async () => {
@@ -101,9 +136,9 @@ export const SetupDatabaseExtensions = async () => {
 export const CreateEntityTable = async () => {
     await db`CREATE TABLE IF NOT EXISTS entities (
         id UUID PRIMARY KEY,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW(),
-        deleted_at TIMESTAMP
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        deleted_at TIMESTAMPTZ
     );`;
 
     // Add partial index for soft-delete queries - critical for 1M+ scale
@@ -148,9 +183,9 @@ export const CreateComponentTable = async () => {
             type_id varchar(64) NOT NULL,
             name varchar(128),
             data jsonb,
-            created_at TIMESTAMP DEFAULT NOW(),
-            updated_at TIMESTAMP DEFAULT NOW(),
-            deleted_at TIMESTAMP,
+            created_at TIMESTAMPTZ DEFAULT NOW(),
+            updated_at TIMESTAMPTZ DEFAULT NOW(),
+            deleted_at TIMESTAMPTZ,
             PRIMARY KEY (id, type_id),
             UNIQUE(entity_id, type_id)
         ) PARTITION BY LIST (type_id);`;
@@ -257,9 +292,9 @@ export const CreateHashPartitionedComponentTable = async (partitionCount: number
         type_id varchar(64) NOT NULL,
         name varchar(128),
         data jsonb,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW(),
-        deleted_at TIMESTAMP,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        deleted_at TIMESTAMPTZ,
         PRIMARY KEY (id, type_id),
         UNIQUE(entity_id, type_id)
     ) PARTITION BY HASH (type_id);`;
@@ -483,9 +518,9 @@ export const CreateEntityComponentTable = async () => {
         entity_id UUID REFERENCES entities(id) ON DELETE CASCADE,
         type_id VARCHAR(64) NOT NULL,
         component_id UUID,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW(),
-        deleted_at TIMESTAMP,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        deleted_at TIMESTAMPTZ,
         UNIQUE(entity_id, type_id)
     );`;
     const concurrently = process.env.USE_PGLITE ? '' : ' CONCURRENTLY';
@@ -646,9 +681,9 @@ export const BenchmarkPartitionCounts = async (partitionCounts: number[] = [8, 1
             type_id varchar(64) NOT NULL,
             name varchar(128),
             data jsonb,
-            created_at TIMESTAMP DEFAULT NOW(),
-            updated_at TIMESTAMP DEFAULT NOW(),
-            deleted_at TIMESTAMP,
+            created_at TIMESTAMPTZ DEFAULT NOW(),
+            updated_at TIMESTAMPTZ DEFAULT NOW(),
+            deleted_at TIMESTAMPTZ,
             PRIMARY KEY (id, type_id),
             UNIQUE(entity_id, type_id)
         ) PARTITION BY HASH (type_id);`);

package/endpoints/entity.ts

@@ -1,8 +1,93 @@
 import db from "../database";
-import type { EntityInspectorResponse } from "./types";
+import type {
+    EntityInspectorResponse,
+    StudioEntityListQueryParams,
+    StudioEntityListResponse,
+    EntityListItem,
+} from "./types";
 
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+export async function handleEntityListRequest(
+    params: StudioEntityListQueryParams = {}
+): Promise<Response> {
+    const limit = Math.min(Math.max(params.limit ?? 50, 1), 1000);
+    const offset = Math.max(params.offset ?? 0, 0);
+    const searchTerm = params.search?.trim() ?? "";
+    const includeDeleted = params.include_deleted ?? false;
+
+    const deletedFilter = includeDeleted ? "" : "AND e.deleted_at IS NULL";
+
+    try {
+        let rows: Record<string, unknown>[];
+        let totalResult: { count: number }[];
+
+        if (searchTerm) {
+            const searchPattern = `%${searchTerm}%`;
+            rows = await db.unsafe(
+                `SELECT e.id, e.created_at, e.updated_at, e.deleted_at,
+                        (SELECT COUNT(*) FROM components c
+                         WHERE c.entity_id = e.id AND c.deleted_at IS NULL) AS component_count
+                 FROM entities e
+                 WHERE e.id::text ILIKE $1 ${deletedFilter}
+                 ORDER BY e.created_at DESC NULLS LAST
+                 LIMIT $2 OFFSET $3`,
+                [searchPattern, limit, offset]
+            );
+            totalResult = await db.unsafe(
+                `SELECT COUNT(*) AS count FROM entities e
+                 WHERE e.id::text ILIKE $1 ${deletedFilter}`,
+                [searchPattern]
+            );
+        } else {
+            rows = await db.unsafe(
+                `SELECT e.id, e.created_at, e.updated_at, e.deleted_at,
+                        (SELECT COUNT(*) FROM components c
+                         WHERE c.entity_id = e.id AND c.deleted_at IS NULL) AS component_count
+                 FROM entities e
+                 WHERE TRUE ${deletedFilter}
+                 ORDER BY e.created_at DESC NULLS LAST
+                 LIMIT $1 OFFSET $2`,
+                [limit, offset]
+            );
+            totalResult = await db.unsafe(
+                `SELECT COUNT(*) AS count FROM entities e WHERE TRUE ${deletedFilter}`
+            );
+        }
+
+        const entities: EntityListItem[] = rows.map((row) => ({
+            id: row.id as string,
+            created_at: row.created_at as string,
+            updated_at: row.updated_at as string,
+            deleted_at: (row.deleted_at as string) ?? null,
+            component_count: Number(row.component_count ?? 0),
+        }));
+
+        const responseData: StudioEntityListResponse = {
+            entities,
+            total: Number(totalResult[0]?.count ?? 0),
+            limit,
+            offset,
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to fetch entities: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}
+
 export async function handleEntityInspectorRequest(
     entityId: string
 ): Promise<Response> {

package/endpoints/index.ts

@@ -7,7 +7,7 @@ import {
     handleStudioArcheTypeRecordsRequest,
     handleStudioArcheTypeDeleteRequest,
 } from "./archetypes";
-import { handleEntityInspectorRequest } from "./entity";
+import { handleEntityInspectorRequest, handleEntityListRequest } from "./entity";
 import { handleStudioStatsRequest } from "./stats";
 import { handleStudioComponentsRequest } from "./components";
 import { handleStudioQueryRequest } from "./query";
@@ -18,6 +18,7 @@ const studioEndpoint = {
     handleStudioTableDeleteRequest,
     handleStudioArcheTypeDeleteRequest,
     handleEntityInspectorRequest,
+    handleEntityListRequest,
     handleStudioStatsRequest,
     handleStudioComponentsRequest,
     handleStudioQueryRequest,

package/endpoints/types.ts

@@ -88,6 +88,28 @@ interface EntityInspectorResponse {
     components: EntityComponent[];
 }
 
+interface StudioEntityListQueryParams {
+    limit?: number;
+    offset?: number;
+    search?: string;
+    include_deleted?: boolean;
+}
+
+interface EntityListItem {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    component_count: number;
+}
+
+interface StudioEntityListResponse {
+    entities: EntityListItem[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
 interface ComponentTypeStats {
     name: string;
     count: number;
@@ -145,6 +167,9 @@ export type {
     DeleteResponse,
     EntityComponent,
     EntityInspectorResponse,
+    StudioEntityListQueryParams,
+    EntityListItem,
+    StudioEntityListResponse,
     ComponentTypeStats,
     ArcheTypeStats,
     StudioStatsResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.5.1",
+    "version": "0.5.3",
     "author": {
         "name": "yaaruu"
     },