@everystack/admin 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@everystack/admin` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.8] - 2026-10-18
+
+### Added
+
+- a table-mapped resource reaches the adapter with its resource name
+
+### Documentation
+
+- select examples use declared relation names; an alias answers 400
+
 ## [0.4.7] - 2026-10-18
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/admin",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Declarative admin dashboard framework for PostgREST APIs",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -134,7 +134,7 @@
     "react-test-renderer": "19.2.0",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/api": "0.4.7",
+    "@everystack/api": "0.4.8",
     "@everystack/ui": "0.4.6"
   },
   "scripts": {

package/src/adapters/types.ts

@@ -41,35 +41,41 @@ export interface DataAdapter {
    * depends on it, and the types cannot enforce it: a custom adapter that drops it
    * lets an id-addressed call reach a row outside the `where` slice.
    * EverystackAdapter honors it on the REST path; its crudRpcs branch ignores it.
+   *
+   * `params.resource` is the resource name, set only when `ResourceConfig.table` maps the
+   * resource to another table (then `resource` above is the table). See ListParams.resource.
    */
   fetchOne<T extends DataRecord = DataRecord>(
     resource: string,
     id: string | number,
-    params?: { select?: string; deleted?: DeletedMode; filter?: Record<string, unknown> }
+    params?: { select?: string; deleted?: DeletedMode; filter?: Record<string, unknown>; resource?: string }
   ): Promise<T>;
 
   /**
-   * Create a new record
+   * Create a new record. `params.resource` is the resource name, set only when
+   * `ResourceConfig.table` maps the resource to another table (then `resource` above is the
+   * table). See ListParams.resource.
    */
-  create<T extends DataRecord = DataRecord>(resource: string, data: Omit<T, 'id'>): Promise<T>;
+  create<T extends DataRecord = DataRecord>(resource: string, data: Omit<T, 'id'>, params?: { resource?: string }): Promise<T>;
 
   /**
    * Update an existing record. `params.deleted` lets the write match a
    * soft-deleted row: Restore sends `{ [column]: null }` with `{ deleted: 'only' }`.
    * `params.filter` is ANDed with the id in the write itself (see fetchOne).
+   * `params.resource`: see fetchOne.
    */
   update<T extends DataRecord = DataRecord>(
     resource: string,
     id: string | number,
     data: Partial<T>,
-    params?: { deleted?: DeletedMode; filter?: Record<string, unknown> }
+    params?: { deleted?: DeletedMode; filter?: Record<string, unknown>; resource?: string }
   ): Promise<T>;
 
   /**
    * Delete a record. `params.filter` is ANDed with the id in the delete itself
-   * (see fetchOne).
+   * (see fetchOne). `params.resource`: see fetchOne.
    */
-  delete(resource: string, id: string | number, params?: { filter?: Record<string, unknown> }): Promise<void>;
+  delete(resource: string, id: string | number, params?: { filter?: Record<string, unknown>; resource?: string }): Promise<void>;
 
   /**
    * Fetch aggregate data (count, sum, avg, min, max) with optional grouping.

package/src/types.ts

@@ -370,8 +370,9 @@ export interface ResourceConfig {
   primaryKey?: string;
   /**
    * PostgREST select string for list, show and edit, embeds included, e.g.
-   * '*,user:users(name)'. One string for all three. Show an embedded value
-   * through a field `render`. RPC-backed resources ignore it.
+   * '*,user(name)', where `user` is a relation declared in the handler's `relations`.
+   * One string for all three. Show an embedded value through a field `render`.
+   * RPC-backed resources ignore it.
    */
   select?: string;
   /**
@@ -379,7 +380,9 @@ export interface ResourceConfig {
    * share a table, each with its own `where` (single-table inheritance). The URL, nav,
    * `relation.resource`, scopes and `where` stay keyed by the resource name; the adapter receives
    * the table name, so an adapter's own per-resource keys (EverystackAdapter `listRpcs` and
-   * `crudRpcs`) use the table name. A resource `dashboard` does NOT follow `table`: its
+   * `crudRpcs`) use the table name. When the table is not the name, the call also carries the
+   * resource name as `params.resource` (a third argument on create), so a custom adapter can still
+   * tell two resources on one table apart. A resource `dashboard` does NOT follow `table`: its
    * `dashboard.tableName` still defaults to the resource name, so set it when `table` is set.
    */
   table?: string;
@@ -725,6 +728,15 @@ export type DeletedMode = 'include' | 'only';
 export type WhereValues = Record<string, string | number | boolean>;
 
 export interface ListParams {
+  /**
+   * The resource name, set only when `ResourceConfig.table` maps the resource to another table.
+   * The adapter's `resource` argument is then the table, and this is the resource that asked, so
+   * an adapter with per-resource flows can still tell two resources on one table apart. Absent
+   * when the table is the name: the `resource` argument IS the resource. The library sets it; a caller
+   * must not pass it, and for a resource that sets no `table` it is passed through as given. The same key rides on
+   * AggregateParams and on the params of fetchOne, create, update and delete.
+   */
+  resource?: string;
   /** Page number (1-indexed) */
   page?: number;
   /** Items per page */
@@ -747,8 +759,8 @@ export interface ListParams {
    */
   searchFields?: string[];
   /**
-   * PostgREST select string, embeds included, e.g. '*,user:users(name)'.
-   * Passed verbatim to the query builder. Ignored by RPC-backed resources
+   * PostgREST select string, embeds included, e.g. '*,user(name)' for a relation
+   * declared in the handler's `relations`. Passed verbatim to the query builder. Ignored by RPC-backed resources
    * (listRpcs); an RPC decides its own shape.
    */
   select?: string;
@@ -793,6 +805,8 @@ export interface AggregateQuery {
 }
 
 export interface AggregateParams {
+  /** The resource name when `ResourceConfig.table` maps it to another table. See ListParams.resource. */
+  resource?: string;
   /** Aggregate functions to compute */
   aggregates: AggregateQuery[];
   /** Columns to group by */

package/src/utils/resource-query.ts

@@ -45,6 +45,15 @@ export function whereFilter(filter: Filter | undefined, where: WhereValues): Fil
   return out;
 }
 
+/**
+ * `params` carrying the resource name, for a resource whose `table` is not its name. The name is
+ * set last, so a caller cannot override it. For any other resource `params` is returned as is, so
+ * an adapter sees no new key.
+ */
+function named<P extends object>(resource: string, q: ResourceQuery, params: P): P {
+  return q.table === resource ? params : { ...params, resource };
+}
+
 /** What the wrapper does for one resource: the table it names, its `where`, if any, and its id column. */
 interface ResourceQuery {
   table: string;
@@ -139,7 +148,10 @@ function checkRow<T>(resource: string, q: ResourceQuery, where: WhereValues, row
 /**
  * The adapter, with every call for a resource that sets `table` or `where` rewritten on the way in.
  * The resource name becomes its table for fetchList, aggregate, fetchOne, create, update, delete and
- * subscribe. `where` narrows the call to its slice: lists, counts and aggregates get it as a filter;
+ * subscribe. When that table is not the name, the call also carries the resource name as
+ * `params.resource` (a third argument on create), so an adapter that serves two resources on one
+ * table can tell them apart. subscribe does not carry it: its events are delivered under the
+ * resource name already. `where` narrows the call to its slice: lists, counts and aggregates get it as a filter;
  * fetchOne, update and delete get it as `params.filter` beside the id, in the one request they send;
  * create and update bodies get the `where` values over the form's. The row that create, update or
  * fetchOne returns is checked against `where`, and one outside it throws, naming it. subscribe
@@ -160,30 +172,33 @@ export function withResourceQuery(adapter: DataAdapter, config: AdminConfig): Da
     fetchList<T extends DataRecord = DataRecord>(resource: string, params: ListParams): Promise<ListResult<T>> {
       const q = queries.get(resource);
       if (!q) return adapter.fetchList<T>(resource, params);
-      return adapter.fetchList<T>(q.table, q.where ? { ...params, filter: whereFilter(params.filter, q.where) } : params);
+      return adapter.fetchList<T>(q.table, named(resource, q, q.where ? { ...params, filter: whereFilter(params.filter, q.where) } : params));
     },
     aggregate(resource: string, params: AggregateParams): Promise<AggregateResult> {
       const q = queries.get(resource);
       if (!q) return adapter.aggregate!(resource, params);
-      return adapter.aggregate!(q.table, q.where ? { ...params, filter: whereFilter(params.filter, q.where) } : params);
+      return adapter.aggregate!(q.table, named(resource, q, q.where ? { ...params, filter: whereFilter(params.filter, q.where) } : params));
     },
     fetchOne<T extends DataRecord = DataRecord>(resource: string, id: string | number, ...rest: [params?: FetchOneParams]): Promise<T> {
       const q = queries.get(resource);
       if (!q) return adapter.fetchOne<T>(resource, id, ...rest);
-      if (!q.where) return adapter.fetchOne<T>(q.table, id, ...rest);
       const [params] = rest;
+      // No where means the table differs from the name (queriesOf), so the name is always sent.
+      if (!q.where) return adapter.fetchOne<T>(q.table, id, named(resource, q, { ...params }));
       const where = q.where;
       return adapter
-        .fetchOne<T>(q.table, id, { ...params, filter: whereFilter(params?.filter, where) })
+        .fetchOne<T>(q.table, id, named(resource, q, { ...params, filter: whereFilter(params?.filter, where) }))
         .then(row => checkRow(resource, q, where, row, false));
     },
     create<T extends DataRecord = DataRecord>(resource: string, data: Omit<T, 'id'>): Promise<T> {
       const q = queries.get(resource);
       if (!q) return adapter.create<T>(resource, data);
-      if (!q.where) return adapter.create<T>(q.table, data);
+      // A third argument only when the table is not the name: every other create keeps its two.
+      const rest: [params?: { resource?: string }] = q.table === resource ? [] : [{ resource }];
+      if (!q.where) return adapter.create<T>(q.table, data, ...rest);
       const where = q.where;
       warnOverridden(resource, data, where);
-      return adapter.create<T>(q.table, { ...data, ...where }).then(row => checkRow(resource, q, where, row, true));
+      return adapter.create<T>(q.table, { ...data, ...where }, ...rest).then(row => checkRow(resource, q, where, row, true));
     },
     update<T extends DataRecord = DataRecord>(
       resource: string,
@@ -193,20 +208,20 @@ export function withResourceQuery(adapter: DataAdapter, config: AdminConfig): Da
     ): Promise<T> {
       const q = queries.get(resource);
       if (!q) return adapter.update<T>(resource, id, data, ...rest);
-      if (!q.where) return adapter.update<T>(q.table, id, data, ...rest);
       const [params] = rest;
+      if (!q.where) return adapter.update<T>(q.table, id, data, named(resource, q, { ...params }));
       const where = q.where;
       warnOverridden(resource, data, where);
       return adapter
-        .update<T>(q.table, id, { ...data, ...where } as Partial<T>, { ...params, filter: whereFilter(params?.filter, where) })
+        .update<T>(q.table, id, { ...data, ...where } as Partial<T>, named(resource, q, { ...params, filter: whereFilter(params?.filter, where) }))
         .then(row => checkRow(resource, q, where, row, true));
     },
     delete(resource: string, id: string | number, ...rest: [params?: DeleteParams]): Promise<void> {
       const q = queries.get(resource);
       if (!q) return adapter.delete(resource, id, ...rest);
-      if (!q.where) return adapter.delete(q.table, id, ...rest);
       const [params] = rest;
-      return adapter.delete(q.table, id, { ...params, filter: whereFilter(params?.filter, q.where) });
+      if (!q.where) return adapter.delete(q.table, id, named(resource, q, { ...params }));
+      return adapter.delete(q.table, id, named(resource, q, { ...params, filter: whereFilter(params?.filter, q.where) }));
     },
     subscribe<T extends DataRecord = DataRecord>(resource: string, callback: (event: SubscriptionEvent<T>) => void): () => void {
       const q = queries.get(resource);