@simtlix/simfinity-js 3.11.0 → 3.12.0

package/README.md

@@ -32,7 +32,7 @@ Text filters compile to escaped regular expressions, so a value never becomes re
 
 The adapter also declares `queryFeatures.referenceEmptiness`, so these operators cross single references and end at references and collections, such as `director IS_EMPTY`, `director.name IS_EMPTY` or `seasons IS_EMPTY`, and an embedded object with a reference or collection member follows the member rule. A crossing joins the target with `$lookup` and `$unwind`, and the target's `id` right after it is its record identity, which is empty exactly when the reference is. A reference or collection is a frame: one `$lookup` that keeps at most one record id, so it never repeats a document, matched with `"alias.0": { $exists: false }` and its `$nor`; a collection frame reads the child's connection field and also tests its local key for null, because `$lookup` matches a missing local key with every child whose connection field is null. The joins and frames run before the `$match`, so they also filter counts, aggregates and batched collection reads, and they probe the `_id` index or the index on the connection field, which generated models create and a supplied model needs to declare. A client's condition reads each target through its `find` scope, inside the `$lookup` pipeline, so a record the scope hides reads as missing, also on the way to a later hop. Conditions that middleware and scopes add, and `buildQuery()` called directly, read stored data, so a dangling reference, to a record that no longer exists, is empty. A related type without a model fails with `INVALID_FILTER_PATH` (400), as for the other operators, and supplied models on another database or connection and discriminator targets are not supported, as for every relation path. A collection inside an embedded type, which only a supplied model can declare, is read through the embedded object's `_id`, as relation paths read it. The [query scope guide](https://simtlix.github.io/simfinity.js/guide/query-scope.html) describes client and trusted conditions, and the [middleware guide](https://simtlix.github.io/simfinity.js/guide/middleware.html) how to edit client filters without detaching them.
 
-The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. Supplied models may use another connection, such as one from `mongoose.createConnection()`: generated mutations and `saveObject()` use the model's connection, and, in the default `referentialIntegrity: 'off'` mode, custom mutations use the default connection unless it is unused, never opened and without compiled models, also on its `useDb()` descendants, and the registered models share one MongoDB client; with transactional reference integrity they use the first protected model's connection. Custom queries registered with `registerCustomQuery()` receive no session; a callback that needs a transaction opens it with the `transaction()` of the Mongoose connection whose models it reads. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
+The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. Supplied models may use another connection, such as one from `mongoose.createConnection()`: generated mutations and `saveObject()` use the model's connection, and, in the default `referentialIntegrity: 'off'` mode, custom mutations use the default connection unless it is unused, never opened and without compiled models, also on its `useDb()` descendants, and the registered models share one MongoDB client; with transactional reference integrity they use the first protected model's connection. Named views need no session: they run the generated list path. Custom queries registered with `registerCustomQuery()` receive no session; a callback that needs a transaction opens it with the `transaction()` of the Mongoose connection whose models it reads. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
 
 Mongoose 8.24.2 or later within version 8 is required to exclude the update-casting prototype-pollution vulnerability. Existing applications should update Mongoose and their dependency lockfile, then run `npm audit`; upgrading Simfinity does not refresh every transitive dependency already locked by the application.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "MongoDB/Mongoose adapter and compatibility facade for Simfinity GraphQL APIs",
   "main": "src/index.js",
   "types": "./types/index.d.ts",
@@ -29,8 +29,8 @@
     "owner": "simtlix"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.11.0",
-    "@simtlix/simfinity-mcp": "3.11.0"
+    "@simtlix/simfinity-core": "3.12.0",
+    "@simtlix/simfinity-mcp": "3.12.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -23,6 +23,7 @@ export const getRegistrations = runtime.getRegistrations;
 export const use = runtime.use;
 export const registerMutation = runtime.registerMutation;
 export const registerCustomQuery = runtime.registerCustomQuery;
+export const registerView = runtime.registerView;
 export const saveObject = runtime.saveObject;
 export const preventCreatingCollection = runtime.preventCreatingCollection;
 

package/types/index.d.ts

@@ -19,6 +19,7 @@ import type {
   QueryFeatures,
   RuntimeRegistration,
   SimfinityError,
+  ViewOptions,
 } from '@simtlix/simfinity-core';
 export {
   auth,
@@ -40,6 +41,8 @@ export type {
   EnvelopSchemaPlugin,
   FieldValidations,
   FieldValidator,
+  FilterCondition,
+  FilterGroup,
   ItemValidators,
   MutationLimitsOptions,
   PermissionSchema,
@@ -49,6 +52,9 @@ export type {
   ScopeParams,
   TypePermissions,
   TypeScopes,
+  ViewOptions,
+  ViewParam,
+  ViewParamType,
   VirtualFieldDeclaration,
   VirtualFieldOptions,
 } from '@simtlix/simfinity-core';
@@ -227,6 +233,14 @@ export function registerCustomQuery(
   callback: (input: any, context: any) => any,
 ): void;
 
+/**
+ * Register a named view: a root query field that returns the type's list with the generated list
+ * arguments plus the view's params, and appends the groups of `where` after middleware. Throws
+ * `INVALID_VIEW` (500) for an invalid declaration and `QUERY_NAME_CONFLICT` (500) for a name already
+ * registered as a view (see the core `Runtime.registerView`).
+ */
+export function registerView(name: string, options: ViewOptions): void;
+
 /** Operation context for root operations, generated non-embedded relation reads, and nested collection writes. */
 export interface SimfinityMiddlewareContext {
   args: any;