@molecule/api-resource 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Base resource patterns for molecule.dev.
+ *
+ * Provides CRUD operation factories and request handler utilities for
+ * building RESTful API resources. Every `@molecule/api-resource-*` package
+ * (user, project, device, ...) is built on these factories.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod'
+ *
+ * import {
+ *   createRequestHandler,
+ *   create,
+ *   read,
+ *   update,
+ *   del,
+ *   query,
+ *   type MoleculeRequest,
+ * } from '@molecule/api-resource'
+ * import { types } from '@molecule/api-resource'
+ * import { basePropsSchema } from '@molecule/api-resource/schema'
+ *
+ * // Every resource schema extends basePropsSchema (id/createdAt/updatedAt).
+ * const userSchema = basePropsSchema.extend({ name: z.string(), email: z.string() })
+ * type UserProps = z.infer<typeof userSchema>
+ *
+ * // Each CRUD factory takes the resource descriptor and returns an async
+ * // operation, e.g. ({ props }) or ({ id }) => { statusCode, body }
+ * // One descriptor, typed as Resource, drives every CRUD factory:
+ * const userResource: types.Resource = { name: 'User', tableName: 'users', schema: userSchema }
+ *
+ * const createUser = create<UserProps>(userResource)
+ * const updateUser = update<UserProps>(userResource)
+ * // read/del type their descriptor with the concrete props — cast the shared one:
+ * const readUser = read(userResource as types.Resource<UserProps>)
+ * const deleteUser = del(userResource as types.Resource<UserProps>)
+ *
+ * // Operations do NOT take (req, res) directly — adapt each one by mapping
+ * // request fields (req.body, req.params.id) to its arguments, then wrap
+ * // with createRequestHandler for Express
+ * const requestHandlerMap = {
+ *   create: createRequestHandler(async (req: MoleculeRequest) =>
+ *     await createUser({ props: req.body }),
+ *   ),
+ *   read: createRequestHandler(async (req: MoleculeRequest) =>
+ *     await readUser({ id: req.params.id }),
+ *   ),
+ *   // ...
+ * }
+ * ```
+ *
+ * @remarks
+ * Working WITH installed `@molecule/api-resource-*` packages (auth `getUserId`,
+ * table ownership, migrations) — what generated code most often breaks:
+ *
+ * - **Auth inside a handler is `const userId = getUserId(res)`, imported from
+ *   `@molecule/api-bonds-default-express`** — NOT from this package (this
+ *   package's `utilities` namespace holds only validation helpers). Return 401
+ *   when it is missing. There is NO `requireAuth` middleware or file to import
+ *   or create; auth is applied at the router level. A route's authorizer may
+ *   also stash the already-loaded row on the response context and hand it to
+ *   `read({ id, props })` to skip a second database fetch.
+ * - **A selected `@molecule/api-resource-*` package OWNS its table AND its
+ *   already-wired routes with a FIXED schema** (e.g. `api-resource-project` owns
+ *   `projects` keyed by `user_id` with a live `/projects` handler). Do NOT write
+ *   a migration that re-creates such a table with a different schema — your
+ *   `CREATE TABLE` shadows theirs (or vice-versa) and the package's still-wired
+ *   handler then 500s (`column "user_id" does not exist`). To model a different
+ *   shape, use a DIFFERENT table name (e.g. `workspace_projects`) + your own
+ *   handler. Check `api/migrations/*` + `api/__setup__/` for tables packages
+ *   already provide.
+ * - **Adding a resource package AFTER scaffold? Copy its migration.** Such a
+ *   package ships its table DDL at `node_modules/@molecule/<pkg>/src/__setup__/*.sql`
+ *   — copy it into `api/migrations/<next-number>_<name>.sql`. Wiring its
+ *   routes/handler alone does NOT create the table: every request 500s with
+ *   "relation does not exist" even though the build type-checks clean. (Only
+ *   packages present at scaffold time get their migration auto-created.)
+ * - **Zod/validation helpers are NAMESPACED exports**, not top-level:
+ *   `schema.basePropsSchema` / `schema.validate` / `schema.safeParse` /
+ *   `schema.partial` / `schema.pick`, and `utilities.getValidProps`
+ *   (re-exported from `@molecule/api-utilities-validation`). Import the
+ *   namespace: `import { schema, utilities } from '@molecule/api-resource'`.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './create.js';
+export * from './createRequestHandler.js';
+export * from './del.js';
+export * from './http-types.js';
+export * from './i18n.js';
+export * from './query.js';
+export * from './read.js';
+export * from './respond-error.js';
+export * as schema from './schema.js';
+export * as types from './types.js';
+export * from './update.js';
+export * as utilities from './utilities/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,100 @@
+/**
+ * Base resource patterns for molecule.dev.
+ *
+ * Provides CRUD operation factories and request handler utilities for
+ * building RESTful API resources. Every `@molecule/api-resource-*` package
+ * (user, project, device, ...) is built on these factories.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod'
+ *
+ * import {
+ *   createRequestHandler,
+ *   create,
+ *   read,
+ *   update,
+ *   del,
+ *   query,
+ *   type MoleculeRequest,
+ * } from '@molecule/api-resource'
+ * import { types } from '@molecule/api-resource'
+ * import { basePropsSchema } from '@molecule/api-resource/schema'
+ *
+ * // Every resource schema extends basePropsSchema (id/createdAt/updatedAt).
+ * const userSchema = basePropsSchema.extend({ name: z.string(), email: z.string() })
+ * type UserProps = z.infer<typeof userSchema>
+ *
+ * // Each CRUD factory takes the resource descriptor and returns an async
+ * // operation, e.g. ({ props }) or ({ id }) => { statusCode, body }
+ * // One descriptor, typed as Resource, drives every CRUD factory:
+ * const userResource: types.Resource = { name: 'User', tableName: 'users', schema: userSchema }
+ *
+ * const createUser = create<UserProps>(userResource)
+ * const updateUser = update<UserProps>(userResource)
+ * // read/del type their descriptor with the concrete props — cast the shared one:
+ * const readUser = read(userResource as types.Resource<UserProps>)
+ * const deleteUser = del(userResource as types.Resource<UserProps>)
+ *
+ * // Operations do NOT take (req, res) directly — adapt each one by mapping
+ * // request fields (req.body, req.params.id) to its arguments, then wrap
+ * // with createRequestHandler for Express
+ * const requestHandlerMap = {
+ *   create: createRequestHandler(async (req: MoleculeRequest) =>
+ *     await createUser({ props: req.body }),
+ *   ),
+ *   read: createRequestHandler(async (req: MoleculeRequest) =>
+ *     await readUser({ id: req.params.id }),
+ *   ),
+ *   // ...
+ * }
+ * ```
+ *
+ * @remarks
+ * Working WITH installed `@molecule/api-resource-*` packages (auth `getUserId`,
+ * table ownership, migrations) — what generated code most often breaks:
+ *
+ * - **Auth inside a handler is `const userId = getUserId(res)`, imported from
+ *   `@molecule/api-bonds-default-express`** — NOT from this package (this
+ *   package's `utilities` namespace holds only validation helpers). Return 401
+ *   when it is missing. There is NO `requireAuth` middleware or file to import
+ *   or create; auth is applied at the router level. A route's authorizer may
+ *   also stash the already-loaded row on the response context and hand it to
+ *   `read({ id, props })` to skip a second database fetch.
+ * - **A selected `@molecule/api-resource-*` package OWNS its table AND its
+ *   already-wired routes with a FIXED schema** (e.g. `api-resource-project` owns
+ *   `projects` keyed by `user_id` with a live `/projects` handler). Do NOT write
+ *   a migration that re-creates such a table with a different schema — your
+ *   `CREATE TABLE` shadows theirs (or vice-versa) and the package's still-wired
+ *   handler then 500s (`column "user_id" does not exist`). To model a different
+ *   shape, use a DIFFERENT table name (e.g. `workspace_projects`) + your own
+ *   handler. Check `api/migrations/*` + `api/__setup__/` for tables packages
+ *   already provide.
+ * - **Adding a resource package AFTER scaffold? Copy its migration.** Such a
+ *   package ships its table DDL at `node_modules/@molecule/<pkg>/src/__setup__/*.sql`
+ *   — copy it into `api/migrations/<next-number>_<name>.sql`. Wiring its
+ *   routes/handler alone does NOT create the table: every request 500s with
+ *   "relation does not exist" even though the build type-checks clean. (Only
+ *   packages present at scaffold time get their migration auto-created.)
+ * - **Zod/validation helpers are NAMESPACED exports**, not top-level:
+ *   `schema.basePropsSchema` / `schema.validate` / `schema.safeParse` /
+ *   `schema.partial` / `schema.pick`, and `utilities.getValidProps`
+ *   (re-exported from `@molecule/api-utilities-validation`). Import the
+ *   namespace: `import { schema, utilities } from '@molecule/api-resource'`.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './create.js';
+export * from './createRequestHandler.js';
+export * from './del.js';
+export * from './http-types.js';
+export * from './i18n.js';
+export * from './query.js';
+export * from './read.js';
+export * from './respond-error.js';
+export * as schema from './schema.js';
+export * as types from './types.js';
+export * from './update.js';
+export * as utilities from './utilities/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,2BAA2B,CAAA;AACzC,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,oBAAoB,CAAA;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAA"}

package/dist/query.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Resource query operation.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import type { MoleculeRequest } from './http-types.js';
+import type * as types from './types.js';
+/**
+ * The available resource query options.
+ *
+ * @example `/api/resources?limit=100&orderBy=updatedAt&after[updatedAt]=2022-02-22T02:22:22.222Z`
+ */
+export interface Query {
+    /**
+     * The maximum number of query results.
+     */
+    limit?: number;
+    /**
+     * An indexed property to order the results by.
+     */
+    orderBy?: `createdAt` | `updatedAt`;
+    /**
+     * The direction to order the results.
+     */
+    orderDirection?: `asc` | `desc`;
+    /**
+     * Constrains the results to values less than these properties, when provided.
+     */
+    before?: {
+        /**
+         * Constrains the results to resources created before the provided timestamp.
+         *
+         * Usually an ISO 8601 timestamp.
+         */
+        createdAt?: string;
+        /**
+         * Constrains the results to resources updated before the provided timestamp.
+         *
+         * Usually an ISO 8601 timestamp.
+         */
+        updatedAt?: string;
+    };
+    /**
+     * Constrains the results to values greater than these properties, when provided.
+     */
+    after?: {
+        /**
+         * Constrains the results to resources created after the provided timestamp.
+         *
+         * Usually an ISO 8601 timestamp.
+         */
+        createdAt?: string;
+        /**
+         * Constrains the results to resources updated after the provided timestamp.
+         *
+         * Usually an ISO 8601 timestamp.
+         */
+        updatedAt?: string;
+    };
+}
+/**
+ * The resource query Zod schema.
+ */
+export declare const querySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    orderBy: z.ZodDefault<z.ZodEnum<{
+        createdAt: "createdAt";
+        updatedAt: "updatedAt";
+    }>>;
+    orderDirection: z.ZodDefault<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    before: z.ZodOptional<z.ZodObject<{
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    after: z.ZodOptional<z.ZodObject<{
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Creates a request handler to be used to query resources.
+ *
+ * Uses the bonded DataStore from `@molecule/api-database` for database-agnostic operations.
+ * @param resource - The resource descriptor.
+ * @param resource.tableName - Database table to query resources from.
+ * @returns A curried async handler that accepts a `MoleculeRequest` (with query params for pagination/sorting) and returns a `{ statusCode, body }` response.
+ */
+export declare const query: <Props extends types.Props = types.Props, QueriedResource extends types.Resource = types.Resource>({ tableName, }: QueriedResource) => (req: MoleculeRequest) => Promise<{
+    statusCode: number;
+    body: {
+        error: string;
+        errorKey: string;
+    };
+} | {
+    statusCode: number;
+    body: Props[];
+}>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAMtD,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,CAAA;IACnC;;OAEG;IACH,cAAc,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE;QACP;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;IACD;;OAEG;IACH,KAAK,CAAC,EAAE;QACN;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,CAAA;KACnB,CAAA;CACF;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;iBAgBtB,CAAA;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAEd,KAAK,SAAS,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EACvC,eAAe,SAAS,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,EACvD,gBAEC,eAAe,MACX,KAAK,eAAe;;;;;;;;;EAqE1B,CAAA"}

package/dist/query.js

@@ -0,0 +1,100 @@
+/**
+ * Resource query operation.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { getLogger } from '@molecule/api-bond';
+const logger = getLogger();
+import { findMany } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+/**
+ * The resource query Zod schema.
+ */
+export const querySchema = z.object({
+    limit: z.coerce.number().min(1).max(10000).default(100),
+    orderBy: z.enum([`createdAt`, `updatedAt`]).default(`updatedAt`),
+    orderDirection: z.enum([`asc`, `desc`]).default(`desc`),
+    before: z
+        .object({
+        createdAt: z.string().optional(),
+        updatedAt: z.string().optional(),
+    })
+        .optional(),
+    after: z
+        .object({
+        createdAt: z.string().optional(),
+        updatedAt: z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Creates a request handler to be used to query resources.
+ *
+ * Uses the bonded DataStore from `@molecule/api-database` for database-agnostic operations.
+ * @param resource - The resource descriptor.
+ * @param resource.tableName - Database table to query resources from.
+ * @returns A curried async handler that accepts a `MoleculeRequest` (with query params for pagination/sorting) and returns a `{ statusCode, body }` response.
+ */
+export const query = ({ tableName, }) => async (req) => {
+    try {
+        // Validate the `req.query`.
+        const result = querySchema.safeParse(req.query);
+        if (!result.success) {
+            // The provided `req.query` failed validation.
+            const errors = result.error.issues
+                .map((e) => `Query.${e.path.join('.')}: ${e.message}`)
+                .join(', ');
+            return { statusCode: 400, body: { error: errors, errorKey: 'resource.error.badRequest' } };
+        }
+        const query = result.data;
+        // Build database-agnostic where conditions.
+        const where = [];
+        if (query.before) {
+            for (const key in query.before) {
+                if (query.before[key]) {
+                    where.push({
+                        field: key,
+                        operator: '<',
+                        value: query.before[key],
+                    });
+                }
+            }
+        }
+        if (query.after) {
+            for (const key in query.after) {
+                if (query.after[key]) {
+                    where.push({
+                        field: key,
+                        operator: '>',
+                        value: query.after[key],
+                    });
+                }
+            }
+        }
+        // Build database-agnostic ordering.
+        const orderBy = [{ field: query.orderBy, direction: query.orderDirection }];
+        // Query the database via the bonded DataStore.
+        const resources = await findMany(tableName, {
+            where: where.length > 0 ? where : undefined,
+            orderBy,
+            limit: query.limit,
+        });
+        if (Array.isArray(resources)) {
+            // A valid response here should always be an array.
+            return { statusCode: 200, body: resources };
+        }
+    }
+    catch (error) {
+        logger.error(error);
+    }
+    // If we made it here, something isn't quite right.
+    return {
+        statusCode: 400,
+        body: {
+            error: t('resource.error.badRequest', undefined, { defaultValue: 'Bad request.' }),
+            errorKey: 'resource.error.badRequest',
+        },
+    };
+};
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/read.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Resource read operation.
+ *
+ * @module
+ */
+import type * as types from './types.js';
+/**
+ * Creates a handler to read a resource by its `id`.
+ *
+ * Uses the bonded DataStore from `@molecule/api-database` for database-agnostic operations.
+ *
+ * Example usage:
+ * ```ts
+ * import { read as resourceRead } from '@molecule/api-resource'
+ * import type * as types from '../../types.js'
+ *
+ * export const read = ({ name, tableName, schema }: types.Resource) => {
+ *   const read = resourceRead({ name, tableName, schema })
+ *
+ *   return async (req: MoleculeRequest) => {
+ *     const id = req.params.id
+ *     return await read({ id })
+ *   }
+ * }
+ * ```
+ * @param resource - The resource descriptor.
+ * @param resource.tableName - Database table to query the resource from.
+ * @returns A curried async function that accepts `{ id, props? }` and returns a `{ statusCode, body }` response.
+ */
+export declare const read: <ReadProps extends types.Props = types.Props, ReadResource extends types.Resource<ReadProps> = types.Resource<ReadProps>>({ tableName, }: ReadResource) => ({ id, props, }: {
+    /**
+     * The `id` of the resource to be retrieved from the database.
+     */
+    id: ReadProps["id"];
+    /**
+     * If you already have the resource's props (e.g., an authorizer assigned them to context),
+     * you can avoid another database query by passing them through.
+     *
+     * Otherwise, the props will be retrieved from the database using the `id`.
+     */
+    props?: ReadProps;
+}) => Promise<{
+    statusCode: number;
+    body: {
+        props: ReadProps;
+        error?: undefined;
+        errorKey?: undefined;
+    };
+} | {
+    statusCode: number;
+    body: {
+        error: string;
+        errorKey: string;
+        props?: undefined;
+    };
+}>;
+//# sourceMappingURL=read.d.ts.map

package/dist/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,IAAI,GAEb,SAAS,SAAS,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAC3C,YAAY,SAAS,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAC1E,gBAEC,YAAY,MACR,gBAGJ;IACD;;OAEG;IACH,EAAE,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;;;;;;;;;;;;;;EAuBA,CAAA"}

package/dist/read.js

@@ -0,0 +1,56 @@
+/**
+ * Resource read operation.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+const logger = getLogger();
+import { findById } from '@molecule/api-database';
+import { t } from '@molecule/api-i18n';
+/**
+ * Creates a handler to read a resource by its `id`.
+ *
+ * Uses the bonded DataStore from `@molecule/api-database` for database-agnostic operations.
+ *
+ * Example usage:
+ * ```ts
+ * import { read as resourceRead } from '@molecule/api-resource'
+ * import type * as types from '../../types.js'
+ *
+ * export const read = ({ name, tableName, schema }: types.Resource) => {
+ *   const read = resourceRead({ name, tableName, schema })
+ *
+ *   return async (req: MoleculeRequest) => {
+ *     const id = req.params.id
+ *     return await read({ id })
+ *   }
+ * }
+ * ```
+ * @param resource - The resource descriptor.
+ * @param resource.tableName - Database table to query the resource from.
+ * @returns A curried async function that accepts `{ id, props? }` and returns a `{ statusCode, body }` response.
+ */
+export const read = ({ tableName, }) => async ({ id, props, }) => {
+    try {
+        if (!props || props.id !== id) {
+            // Read the resource from the database via the bonded DataStore.
+            props = (await findById(tableName, id)) ?? undefined;
+        }
+        if (props && props.id === id) {
+            // Found the resource.
+            return { statusCode: 200, body: { props } };
+        }
+    }
+    catch (error) {
+        logger.error(error);
+    }
+    // If we made it here, the resource could not be found with the provided `id`.
+    return {
+        statusCode: 404,
+        body: {
+            error: t('resource.error.notFound', undefined, { defaultValue: 'Not found.' }),
+            errorKey: 'resource.error.notFound',
+        },
+    };
+};
+//# sourceMappingURL=read.js.map

package/dist/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAItC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,IAAI,GACf,CAGE,EACA,SAAS,GACI,EAAE,EAAE,CACnB,KAAK,EAAE,EACL,EAAE,EACF,KAAK,GAaN,EAAE,EAAE;IACH,IAAI,CAAC;QACH,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;YAC9B,gEAAgE;YAChE,KAAK,GAAG,CAAC,MAAM,QAAQ,CAAY,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,SAAS,CAAA;QACjE,CAAC;QAED,IAAI,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;YAC7B,sBAAsB;YACtB,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,CAAA;QAC7C,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC;IAED,8EAA8E;IAC9E,OAAO;QACL,UAAU,EAAE,GAAG;QACf,IAAI,EAAE;YACJ,KAAK,EAAE,CAAC,CAAC,yBAAyB,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;YAC9E,QAAQ,EAAE,yBAAyB;SACpC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/respond-error.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared error responder for resource handlers.
+ *
+ * @module
+ */
+import type { MoleculeResponse } from './http-types.js';
+/**
+ * Fallback HTTP response used when a caught error is NOT a molecule-tagged error
+ * (i.e. a genuinely-unexpected failure).
+ */
+export interface ErrorFallback {
+    /** HTTP status for the fallback (typically 500). */
+    status: number;
+    /** Human-readable fallback message (already localized by the caller). */
+    message: string;
+    /** Machine-readable key the frontend maps to a localized message. */
+    errorKey: string;
+}
+/**
+ * Respond to a caught handler error, honoring molecule's "tagged error" convention.
+ *
+ * A tagged error carries BOTH a numeric `statusCode` AND a string `errorKey` — the same
+ * contract `@molecule/api-server-default-express`'s error middleware (`classifyTaggedError`)
+ * uses. Providers throw these for expected, user-actionable conditions — e.g. a
+ * config-missing throw (`503` + `'config.notConfigured'`) when `STRIPE_SECRET_KEY` is unset.
+ *
+ * Handlers that catch errors MUST funnel through this instead of a blanket
+ * `res.status(500)`, so a tagged error surfaces its REAL status + errorKey rather than
+ * being flattened to a generic 500. Otherwise the app looks broken at the exact moment the
+ * user tries to use the feature — the worst possible time for a payment (the conversion
+ * path). A swallowed tag is why the middleware-only fix was insufficient: ~185 handlers
+ * catch-and-500, so the tag never reached the middleware.
+ *
+ * Tagged errors are logged at `warn` (expected/actionable, not a server fault); everything
+ * else is logged at `error` and returns the caller's `fallback`. Requiring BOTH fields is
+ * deliberate: it keeps arbitrary library errors that merely carry a `.statusCode` (e.g. an
+ * AWS SDK 403) from being surfaced with a status molecule never chose.
+ *
+ * @param res - The response object.
+ * @param error - The caught error.
+ * @param fallback - Status/message/errorKey to use when `error` isn't a tagged error.
+ */
+export declare function respondError(res: MoleculeResponse, error: unknown, fallback: ErrorFallback): void;
+//# sourceMappingURL=respond-error.d.ts.map

package/dist/respond-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond-error.d.ts","sourceRoot":"","sources":["../src/respond-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAIvD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAejG"}

package/dist/respond-error.js

@@ -0,0 +1,46 @@
+/**
+ * Shared error responder for resource handlers.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+const logger = getLogger();
+/**
+ * Respond to a caught handler error, honoring molecule's "tagged error" convention.
+ *
+ * A tagged error carries BOTH a numeric `statusCode` AND a string `errorKey` — the same
+ * contract `@molecule/api-server-default-express`'s error middleware (`classifyTaggedError`)
+ * uses. Providers throw these for expected, user-actionable conditions — e.g. a
+ * config-missing throw (`503` + `'config.notConfigured'`) when `STRIPE_SECRET_KEY` is unset.
+ *
+ * Handlers that catch errors MUST funnel through this instead of a blanket
+ * `res.status(500)`, so a tagged error surfaces its REAL status + errorKey rather than
+ * being flattened to a generic 500. Otherwise the app looks broken at the exact moment the
+ * user tries to use the feature — the worst possible time for a payment (the conversion
+ * path). A swallowed tag is why the middleware-only fix was insufficient: ~185 handlers
+ * catch-and-500, so the tag never reached the middleware.
+ *
+ * Tagged errors are logged at `warn` (expected/actionable, not a server fault); everything
+ * else is logged at `error` and returns the caller's `fallback`. Requiring BOTH fields is
+ * deliberate: it keeps arbitrary library errors that merely carry a `.statusCode` (e.g. an
+ * AWS SDK 403) from being surfaced with a status molecule never chose.
+ *
+ * @param res - The response object.
+ * @param error - The caught error.
+ * @param fallback - Status/message/errorKey to use when `error` isn't a tagged error.
+ */
+export function respondError(res, error, fallback) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        typeof error.statusCode === 'number' &&
+        typeof error.errorKey === 'string') {
+        const tagged = error;
+        const message = typeof tagged.message === 'string' ? tagged.message : fallback.message;
+        logger.warn(message, { errorKey: tagged.errorKey });
+        res.status(tagged.statusCode).json({ error: message, errorKey: tagged.errorKey });
+        return;
+    }
+    logger.error(fallback.message, { error });
+    res.status(fallback.status).json({ error: fallback.message, errorKey: fallback.errorKey });
+}
+//# sourceMappingURL=respond-error.js.map

package/dist/respond-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond-error.js","sourceRoot":"","sources":["../src/respond-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAI9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAe1B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,GAAqB,EAAE,KAAc,EAAE,QAAuB;IACzF,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAkC,CAAC,UAAU,KAAK,QAAQ;QAClE,OAAQ,KAAgC,CAAC,QAAQ,KAAK,QAAQ,EAC9D,CAAC;QACD,MAAM,MAAM,GAAG,KAAoE,CAAA;QACnF,MAAM,OAAO,GAAG,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAA;QACtF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;QACnD,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;QACjF,OAAM;IACR,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACzC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;AAC5F,CAAC"}