@terreno/api 0.0.3 → 0.0.10

package/README.md

@@ -5,9 +5,9 @@ Most REST APIs wind up being a lot of boilerplate, so this tries to cut that dow
 into a full blown framework of its own. This library is inspired by the
 [Django-REST-Framework](https://www.django-rest-framework.org).
 
-### Coming soon:
-
-A frontend library to consume these APIs with Redux Toolkit Query.
+These APIs integrate with @terreno/rtk to create consistent types on the frontend
+and backend, and automatically generated React hooks to fetch, query, and modify
+model instances.
 
 ## Getting started
 

package/dist/api.d.ts

@@ -22,7 +22,7 @@ export type RESTMethod = "list" | "create" | "read" | "update" | "delete";
  * This is the main configuration.
  * @param T - the base document type. This should not include Mongoose models, just the types of the object.
  */
-export interface modelRouterOptions<T> {
+export interface ModelRouterOptions<T> {
     /**
      * A group of method-level (create/read/update/delete/list) permissions.
      * Determine if the user can perform the operation at all, and for read/update/delete methods,
@@ -180,7 +180,7 @@ export interface modelRouterOptions<T> {
      * This is a good spot to remove sensitive information from the object, such as passwords or API
      * keys. Throw an APIError to return a 400 with an error message.
      */
-    responseHandler?: (value: (Document<any, any, any> & T) | (Document<any, any, any> & T)[], method: "list" | "create" | "read" | "update" | "delete", request: express.Request, options: modelRouterOptions<T>) => Promise<JSONValue>;
+    responseHandler?: (value: (Document<any, any, any> & T) | (Document<any, any, any> & T)[], method: "list" | "create" | "read" | "update" | "delete", request: express.Request, options: ModelRouterOptions<T>) => Promise<JSONValue>;
     /**
      * The discriminatorKey that you passed when creating the Mongoose models. Defaults to __t. See:
      * https://mongoosejs.com/docs/discriminators.html If this key is provided,
@@ -214,14 +214,14 @@ export interface modelRouterOptions<T> {
      */
     openApiExtraModelProperties?: any;
 }
-export declare function getModel(baseModel: Model<any>, body?: any, options?: modelRouterOptions<any>): mongoose.Model<any, {}, {}, {}, any, any, any>;
+export declare function getModel(baseModel: Model<any>, body?: any, options?: ModelRouterOptions<any>): mongoose.Model<any, {}, {}, {}, any, any, any>;
 /**
  * Create a set of CRUD routes given a Mongoose model $baseModel and configuration options.
  *
  * @param baseModel A Mongoose Model
  * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
  */
-export declare function modelRouter<T>(baseModel: Model<T>, options: modelRouterOptions<T>): express.Router;
+export declare function modelRouter<T>(baseModel: Model<T>, options: ModelRouterOptions<T>): express.Router;
 export declare const asyncHandler: (fn: any) => (req: Request, res: Response, next: NextFunction) => Promise<any>;
 export declare const gooseRestRouter: typeof modelRouter;
-export type GooseRESTOptions<T> = modelRouterOptions<T>;
+export type GooseRESTOptions<T> = ModelRouterOptions<T>;

package/dist/expressServer.d.ts

@@ -1,11 +1,11 @@
 import * as Sentry from "@sentry/node";
 import express, { type Router } from "express";
 import type jwt from "jsonwebtoken";
-import type { modelRouterOptions } from "./api";
+import type { ModelRouterOptions } from "./api";
 import { type UserModel as UserMongooseModel } from "./auth";
 import { type LoggingOptions } from "./logger";
 export declare function setupEnvironment(): void;
-export type AddRoutes = (router: Router, options?: Partial<modelRouterOptions<any>>) => void;
+export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<any>>) => void;
 export declare function logRequests(req: any, res: any, next: any): void;
 export declare function createRouter(rootPath: string, addRoutes: AddRoutes, middleware?: any[]): any[];
 export declare function createRouterWithAuth(rootPath: string, addRoutes: (router: Router) => void, middleware?: any[]): any[];

package/dist/openApi.d.ts

@@ -1,5 +1,5 @@
 import type { Model } from "mongoose";
-import type { modelRouterOptions } from "./api";
+import type { ModelRouterOptions } from "./api";
 export declare const apiErrorContent: {
     "application/json": {
         schema: {
@@ -52,9 +52,9 @@ export declare const defaultOpenApiErrorResponses: {
         description: string;
     };
 };
-export declare function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>): any;
-export declare function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>): any;
-export declare function createOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>): any;
-export declare function patchOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>): any;
-export declare function deleteOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>): any;
-export declare function readOpenApiMiddleware<T>(options: Partial<modelRouterOptions<T>>, properties: any, required: string[], queryParameters: any): any;
+export declare function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
+export declare function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
+export declare function createOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
+export declare function patchOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
+export declare function deleteOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>): any;
+export declare function readOpenApiMiddleware<T>(options: Partial<ModelRouterOptions<T>>, properties: any, required: string[], queryParameters: any): any;

package/dist/openApiBuilder.d.ts

@@ -1,4 +1,4 @@
-import type { modelRouterOptions } from "./api";
+import type { ModelRouterOptions } from "./api";
 /**
  * Defines a property within an OpenAPI schema.
  *
@@ -189,7 +189,7 @@ export declare class OpenApiMiddlewareBuilder {
      *
      * @param options - Router options containing the OpenAPI path configuration
      */
-    constructor(options: Partial<modelRouterOptions<any>>);
+    constructor(options: Partial<ModelRouterOptions<any>>);
     /**
      * Sets the tags for the OpenAPI operation.
      *
@@ -416,4 +416,4 @@ export declare class OpenApiMiddlewareBuilder {
  * router.get("/analytics/stats", statsMiddleware, getStatsHandler);
  * ```
  */
-export declare function createOpenApiBuilder(options: Partial<modelRouterOptions<any>>): OpenApiMiddlewareBuilder;
+export declare function createOpenApiBuilder(options: Partial<ModelRouterOptions<any>>): OpenApiMiddlewareBuilder;

package/dist/permissions.d.ts

@@ -1,7 +1,7 @@
 import type express from "express";
 import type { NextFunction } from "express";
 import { type Model } from "mongoose";
-import { type modelRouterOptions, type RESTMethod } from "./api";
+import { type ModelRouterOptions, type RESTMethod } from "./api";
 import type { User } from "./auth";
 export type PermissionMethod<T> = (method: RESTMethod, user?: User, obj?: T) => boolean | Promise<boolean>;
 export interface RESTPermissions<T> {
@@ -23,4 +23,4 @@ export declare const Permissions: {
     IsOwnerOrReadOnly: (method: RESTMethod, user?: User, obj?: any) => boolean;
 };
 export declare function checkPermissions<T>(method: RESTMethod, permissions: PermissionMethod<T>[], user?: User, obj?: T): Promise<boolean>;
-export declare function permissionMiddleware<T>(baseModel: Model<T>, options: Pick<modelRouterOptions<T>, "permissions" | "populatePaths" | "discriminatorKey">): (req: express.Request, _res: express.Response, next: NextFunction) => Promise<void>;
+export declare function permissionMiddleware<T>(baseModel: Model<T>, options: Pick<ModelRouterOptions<T>, "permissions" | "populatePaths" | "discriminatorKey">): (req: express.Request, _res: express.Response, next: NextFunction) => Promise<void>;

package/dist/transformers.d.ts

@@ -1,6 +1,6 @@
 import type express from "express";
 import type { Document } from "mongoose";
-import type { modelRouterOptions } from "./api";
+import type { ModelRouterOptions } from "./api";
 import type { User } from "./auth";
 export interface TerrenoTransformer<T> {
     transform?: (obj: Partial<T>, method: "create" | "update", user?: User) => Partial<T> | undefined;
@@ -16,10 +16,10 @@ export declare function AdminOwnerTransformer<T>(options: {
     ownerWriteFields?: string[];
     adminWriteFields?: string[];
 }): TerrenoTransformer<T>;
-export declare function transform<T>(options: modelRouterOptions<T>, data: Partial<T> | Partial<T>[], method: "create" | "update", user?: User): Partial<T> | (Partial<T> | undefined)[] | undefined;
-export declare function serialize<T>(req: express.Request, options: modelRouterOptions<T>, data: (Document<any, any, any> & T) | (Document<any, any, any> & T)[]): Partial<T> | (Partial<T> | undefined)[] | undefined;
+export declare function transform<T>(options: ModelRouterOptions<T>, data: Partial<T> | Partial<T>[], method: "create" | "update", user?: User): Partial<T> | (Partial<T> | undefined)[] | undefined;
+export declare function serialize<T>(req: express.Request, options: ModelRouterOptions<T>, data: (Document<any, any, any> & T) | (Document<any, any, any> & T)[]): Partial<T> | (Partial<T> | undefined)[] | undefined;
 /**
  * Default response handler for modelRouter. Calls toObject on each doc and returns the result,
  * using transformers.serializer if provided.
  */
-export declare function defaultResponseHandler<T>(doc: (Document<any, any, any> & T) | (Document<any, any, any> & T)[] | null, method: "list" | "create" | "read" | "update", request: express.Request, options: modelRouterOptions<T>): Promise<Partial<T> | (Partial<T> | undefined)[] | null | undefined>;
+export declare function defaultResponseHandler<T>(doc: (Document<any, any, any> & T) | (Document<any, any, any> & T)[] | null, method: "list" | "create" | "read" | "update", request: express.Request, options: ModelRouterOptions<T>): Promise<Partial<T> | (Partial<T> | undefined)[] | null | undefined>;

package/package.json

@@ -84,5 +84,5 @@
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.3"
+  "version": "0.0.10"
 }

package/src/api.ts

@@ -70,7 +70,7 @@ export type RESTMethod = "list" | "create" | "read" | "update" | "delete";
  * This is the main configuration.
  * @param T - the base document type. This should not include Mongoose models, just the types of the object.
  */
-export interface modelRouterOptions<T> {
+export interface ModelRouterOptions<T> {
   /**
    * A group of method-level (create/read/update/delete/list) permissions.
    * Determine if the user can perform the operation at all, and for read/update/delete methods,
@@ -239,7 +239,7 @@ export interface modelRouterOptions<T> {
     value: (Document<any, any, any> & T) | (Document<any, any, any> & T)[],
     method: "list" | "create" | "read" | "update" | "delete",
     request: express.Request,
-    options: modelRouterOptions<T>
+    options: ModelRouterOptions<T>
   ) => Promise<JSONValue>;
   /**
    * The discriminatorKey that you passed when creating the Mongoose models. Defaults to __t. See:
@@ -277,7 +277,7 @@ export interface modelRouterOptions<T> {
 
 // A function to decide which model to use. If no discriminators are provided,
 // just returns the base model. If
-export function getModel(baseModel: Model<any>, body?: any, options?: modelRouterOptions<any>) {
+export function getModel(baseModel: Model<any>, body?: any, options?: ModelRouterOptions<any>) {
   const discriminatorKey = options?.discriminatorKey ?? "__t";
   const modelName = body?.[discriminatorKey];
   if (!modelName) {
@@ -344,7 +344,7 @@ function checkQueryParamAllowed(
  */
 export function modelRouter<T>(
   baseModel: Model<T>,
-  options: modelRouterOptions<T>
+  options: ModelRouterOptions<T>
 ): express.Router {
   const router = express.Router();
 
@@ -1033,4 +1033,4 @@ export const asyncHandler = (fn: any) => (req: Request, res: Response, next: Nex
 
 // For backwards compatibility with the old names.
 export const gooseRestRouter = modelRouter;
-export type GooseRESTOptions<T> = modelRouterOptions<T>;
+export type GooseRESTOptions<T> = ModelRouterOptions<T>;

package/src/example.ts

@@ -2,7 +2,7 @@ import express from "express";
 import mongoose, {model, Schema} from "mongoose";
 import passportLocalMongoose from "passport-local-mongoose";
 
-import {modelRouter, type modelRouterOptions} from "./api";
+import {type ModelRouterOptions, modelRouter} from "./api";
 import {addAuthRoutes, setupAuth} from "./auth";
 import {setupServer} from "./expressServer";
 import {logger} from "./logger";
@@ -68,7 +68,7 @@ function getBaseServer() {
   setupAuth(app, UserModel as any);
   addAuthRoutes(app, UserModel as any);
 
-  function addRoutes(router: express.Router, options?: Partial<modelRouterOptions<any>>): void {
+  function addRoutes(router: express.Router, options?: Partial<ModelRouterOptions<any>>): void {
     router.use(
       "/food",
       modelRouter(FoodModel, {

package/src/expressServer.ts

@@ -9,7 +9,7 @@ import onFinished from "on-finished";
 import passport from "passport";
 import qs from "qs";
 
-import type {modelRouterOptions} from "./api";
+import type {ModelRouterOptions} from "./api";
 import {addAuthRoutes, addMeRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
 import {apiErrorMiddleware, apiUnauthorizedMiddleware} from "./errors";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
@@ -41,7 +41,7 @@ export function setupEnvironment(): void {
   }
 }
 
-export type AddRoutes = (router: Router, options?: Partial<modelRouterOptions<any>>) => void;
+export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<any>>) => void;
 
 const logRequestsFinished = (req: any, res: any, startTime: bigint) => {
   const options = (res.locals.loggingOptions ?? {}) as LoggingOptions;

package/src/openApi.test.ts

@@ -4,13 +4,13 @@ import type {Router} from "express";
 import supertest from "supertest";
 import type TestAgent from "supertest/lib/agent";
 
-import {modelRouter, type modelRouterOptions} from "./api";
+import {type ModelRouterOptions, modelRouter} from "./api";
 import {addAuthRoutes, setupAuth} from "./auth";
 import {setupServer} from "./expressServer";
 import {Permissions} from "./permissions";
 import {FoodModel, setupDb, UserModel} from "./tests";
 
-function getMessageSummaryOpenApiMiddleware(options: Partial<modelRouterOptions<any>>): any {
+function getMessageSummaryOpenApiMiddleware(options: Partial<ModelRouterOptions<any>>): any {
   return options.openApi.path({
     parameters: [
       {
@@ -42,7 +42,7 @@ function getMessageSummaryOpenApiMiddleware(options: Partial<modelRouterOptions<
   });
 }
 
-function addRoutes(router: Router, options?: Partial<modelRouterOptions<any>>): void {
+function addRoutes(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
   router.use(
     "/food",
     modelRouter(FoodModel as any, {
@@ -176,7 +176,7 @@ describe("openApi", () => {
   });
 });
 
-function addRoutesPopulate(router: Router, options?: Partial<modelRouterOptions<any>>): void {
+function addRoutesPopulate(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
   options?.openApi.component("schemas", "LimitedUser", {
     properties: {
       email: {

package/src/openApi.ts

@@ -3,7 +3,7 @@ import merge from "lodash/merge";
 import type {Model} from "mongoose";
 import m2s from "mongoose-to-swagger";
 
-import type {modelRouterOptions} from "./api";
+import type {ModelRouterOptions} from "./api";
 import {logger} from "./logger";
 import {getOpenApiSpecForModel} from "./populate";
 
@@ -112,7 +112,7 @@ function createAPIErrorComponent(openApi: any) {
   });
 }
 
-export function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>) {
+export function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) {
   createAPIErrorComponent(options.openApi);
   if (!options.openApi?.path) {
     // Just log this once rather than for each middleware.
@@ -154,7 +154,7 @@ export function getOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelR
   );
 }
 
-export function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<modelRouterOptions<T>>) {
+export function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) {
   if (!options.openApi?.path) {
     return noop;
   }
@@ -319,7 +319,7 @@ export function listOpenApiMiddleware<T>(model: Model<T>, options: Partial<model
 
 export function createOpenApiMiddleware<T>(
   model: Model<T>,
-  options: Partial<modelRouterOptions<T>>
+  options: Partial<ModelRouterOptions<T>>
 ) {
   if (!options.openApi?.path) {
     return noop;
@@ -371,7 +371,7 @@ export function createOpenApiMiddleware<T>(
 
 export function patchOpenApiMiddleware<T>(
   model: Model<T>,
-  options: Partial<modelRouterOptions<T>>
+  options: Partial<ModelRouterOptions<T>>
 ) {
   if (!options.openApi?.path) {
     return noop;
@@ -423,7 +423,7 @@ export function patchOpenApiMiddleware<T>(
 
 export function deleteOpenApiMiddleware<T>(
   model: Model<T>,
-  options: Partial<modelRouterOptions<T>>
+  options: Partial<ModelRouterOptions<T>>
 ) {
   if (!options.openApi?.path) {
     return noop;
@@ -452,7 +452,7 @@ export function deleteOpenApiMiddleware<T>(
 // This is a generic OpenAPI wrapper for a read that returns any object described by `properties`.
 // Useful for endpoints that don't directly map to a model.
 export function readOpenApiMiddleware<T>(
-  options: Partial<modelRouterOptions<T>>,
+  options: Partial<ModelRouterOptions<T>>,
   properties: any,
   required: string[],
   queryParameters: any

package/src/openApiBuilder.test.ts

@@ -4,14 +4,14 @@ import type {Router} from "express";
 import supertest from "supertest";
 import type TestAgent from "supertest/lib/agent";
 
-import {modelRouter, type modelRouterOptions} from "./api";
+import {type ModelRouterOptions, modelRouter} from "./api";
 import {addAuthRoutes, setupAuth} from "./auth";
 import {setupServer} from "./expressServer";
 import {createOpenApiBuilder, OpenApiMiddlewareBuilder} from "./openApiBuilder";
 import {Permissions} from "./permissions";
 import {FoodModel, UserModel} from "./tests";
 
-function addRoutesWithBuilder(router: Router, options?: Partial<modelRouterOptions<any>>): void {
+function addRoutesWithBuilder(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
   // Add a custom endpoint using the OpenApiMiddlewareBuilder
   const statsMiddleware = createOpenApiBuilder(options ?? {})
     .withTags(["Stats"])

package/src/openApiBuilder.ts

@@ -31,7 +31,7 @@
  */
 import merge from "lodash/merge";
 
-import type {modelRouterOptions} from "./api";
+import type {ModelRouterOptions} from "./api";
 import {logger} from "./logger";
 import {defaultOpenApiErrorResponses} from "./openApi";
 
@@ -250,7 +250,7 @@ interface OpenApiConfig {
  */
 export class OpenApiMiddlewareBuilder {
   /** Router options containing OpenAPI configuration */
-  private options: Partial<modelRouterOptions<any>>;
+  private options: Partial<ModelRouterOptions<any>>;
 
   /** Accumulated OpenAPI configuration from builder methods */
   private config: OpenApiConfig;
@@ -260,7 +260,7 @@ export class OpenApiMiddlewareBuilder {
    *
    * @param options - Router options containing the OpenAPI path configuration
    */
-  constructor(options: Partial<modelRouterOptions<any>>) {
+  constructor(options: Partial<ModelRouterOptions<any>>) {
     this.options = options;
     this.config = {
       responses: {},
@@ -630,7 +630,7 @@ export class OpenApiMiddlewareBuilder {
  * ```
  */
 export function createOpenApiBuilder(
-  options: Partial<modelRouterOptions<any>>
+  options: Partial<ModelRouterOptions<any>>
 ): OpenApiMiddlewareBuilder {
   return new OpenApiMiddlewareBuilder(options);
 }

package/src/permissions.ts

@@ -4,7 +4,7 @@ import type express from "express";
 import type {NextFunction} from "express";
 import mongoose, {type Model} from "mongoose";
 
-import {addPopulateToQuery, getModel, type modelRouterOptions, type RESTMethod} from "./api";
+import {addPopulateToQuery, getModel, type ModelRouterOptions, type RESTMethod} from "./api";
 import type {User} from "./auth";
 import {APIError} from "./errors";
 import {logger} from "./logger";
@@ -102,7 +102,7 @@ export async function checkPermissions<T>(
 // req.obj.
 export function permissionMiddleware<T>(
   baseModel: Model<T>,
-  options: Pick<modelRouterOptions<T>, "permissions" | "populatePaths" | "discriminatorKey">
+  options: Pick<ModelRouterOptions<T>, "permissions" | "populatePaths" | "discriminatorKey">
 ) {
   return async (req: express.Request, _res: express.Response, next: NextFunction) => {
     if (req.method === "OPTIONS") {

package/src/transformers.ts

@@ -1,7 +1,7 @@
 import type express from "express";
 import type {Document} from "mongoose";
 
-import type {modelRouterOptions} from "./api";
+import type {ModelRouterOptions} from "./api";
 import type {User} from "./auth";
 import {APIError} from "./errors";
 import {logger} from "./logger";
@@ -88,7 +88,7 @@ export function AdminOwnerTransformer<T>(options: {
 }
 
 export function transform<T>(
-  options: modelRouterOptions<T>,
+  options: ModelRouterOptions<T>,
   data: Partial<T> | Partial<T>[],
   method: "create" | "update",
   user?: User
@@ -112,7 +112,7 @@ export function transform<T>(
 
 export function serialize<T>(
   req: express.Request,
-  options: modelRouterOptions<T>,
+  options: ModelRouterOptions<T>,
   data: (Document<any, any, any> & T) | (Document<any, any, any> & T)[]
 ) {
   const serializeFn = (serializeData: Document<any, any, any> & T, serializeUser?: User) => {
@@ -153,7 +153,7 @@ export async function defaultResponseHandler<T>(
   doc: (Document<any, any, any> & T) | (Document<any, any, any> & T)[] | null,
   method: "list" | "create" | "read" | "update",
   request: express.Request,
-  options: modelRouterOptions<T>
+  options: ModelRouterOptions<T>
 ) {
   if (!doc) {
     return null;