@m1212e/rumble 0.16.41 → 0.16.47

package/out/index.cjs

@@ -209,7 +209,7 @@ function mapNullFieldsToUndefined(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.16.41";
+var version = "0.16.47";
 //#endregion
 //#region lib/helpers/mergeFilters.ts
 function mergeFilters(filterA, filterB) {
@@ -375,6 +375,9 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 		const runtimeFilters = /* @__PURE__ */ new Map();
 		for (const action of actions) if (!runtimeFilters.has(action)) runtimeFilters.set(action, []);
 		return {
+			/**
+			* Allows to perform a specific action on a specific entity
+			*/
 			allow: (action) => {
 				if (hasBeenBuilt) throw new RumbleError("You can't call allow() after the ability builder has been built. Please ensure that you register all abilities before accessing them.");
 				const actions = Array.isArray(action) ? action : [action];
@@ -385,24 +388,58 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 						queryFilters.set(action, filters);
 					}
 				}
-				return { when: (queryFilter) => {
+				return { 
+				/**
+				* Restricts the allowed actions to a filter
+				* @example
+				* ```ts
+				* abilityBuilder.users.allow(["read", "update", "delete"]).when(({ userId }) => ({
+				*    where: {
+				*      id: userId,
+				*    },
+				*  }));
+				* ```
+				*/
+when: (queryFilter) => {
 					for (const action of actions) {
 						if (queryFilters.get(action) === "unrestricted") queryFilters.set(action, []);
 						queryFilters.get(action).push(queryFilter);
 					}
 				} };
 			},
+			/**
+			* Allows to register an application level filter to restrict some results
+			* which were returned by a query
+			*/
 			filter: (action) => {
 				const actions = Array.isArray(action) ? action : [action];
 				return {
+					/**
+					* Allows to register an application level prefetch to fetch some data
+					* which could be useful for later filtering the results. The prefetch
+					* function will be called with the user context but unlike the actual
+					* filter function, it will not have access to the result of the query
+					* and therefore can be run in parallel with underlying query resolver.
+					* A typical use case is to fetch some data which is not directly
+					* related to the query but to the context only. So e.g. fetching the
+					* user's permissions from an external system and then later applying
+					* the filter based on those permissions.
+					*/
 					prefetch: (prefetch) => {
-						return { by: (explicitFilter) => {
+						return { 
+						/**
+						* The actual filter function to apply. Returns the allowed values
+						*/
+by: (explicitFilter) => {
 							for (const action of actions) runtimeFilters.get(action).push({
 								filter: explicitFilter,
 								prefetch
 							});
 						} };
 					},
+					/**
+					* The actual filter function to apply. Returns the allowed values
+					*/
 					by: (explicitFilter) => {
 						for (const action of actions) runtimeFilters.get(action).push({ filter: explicitFilter });
 					}
@@ -417,6 +454,10 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 	const buildersPerTable = Object.fromEntries(Object.keys(db.query).map((tableName) => [tableName, createBuilderForTable()]));
 	return {
 		...buildersPerTable,
+		/**
+		* @internal
+		* @ignore
+		*/
 		_: {
 			registeredFilters({ action, table }) {
 				return buildersPerTable[table]._.runtimeFilters.get(action);
@@ -461,12 +502,27 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 								return filters?.where ? (0, drizzle_orm.relationsFilterToSQL)(tableSchema.foundRelation.table, filters.where, tableSchema.relations, db._.relations, casing) : void 0;
 							});
 							if (filters?.columns) return {
+								/**
+								* Query filters for the drizzle query API.
+								* @example
+								* ```ts
+								* author: t.relation("author", {
+								*  query: (_args, ctx) => ctx.abilities.users.filter("read").query.single,
+								* }),
+								* ´´´
+								*/
 								query: {
+									/**
+									* For find first calls
+									*/
 									single: {
 										extras: filters?.extras,
 										where: filters?.where,
 										columns: filters?.columns
 									},
+									/**
+									* For find many calls
+									*/
 									many: {
 										extras: filters?.extras,
 										where: filters?.where,
@@ -476,16 +532,50 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 										}
 									}
 								},
+								/**
+								* Query filters for the drizzle SQL API as used in e.g. updates.
+								* @example
+								*
+								* ```ts
+								* await db
+								*	.update(schema.users)
+								*	.set({
+								*	  name: args.newName,
+								* 	})
+								*	.where(
+								*	  and(
+								*	    eq(schema.users.id, args.userId),
+								*	    ctx.abilities.users.filter("update").sql.where,
+								*	  ),
+								*	);
+								* ```
+								*
+								*/
 								sql: { get where() {
 									return sqlTransformedWhere();
 								} }
 							};
 							else return {
+								/**
+								* Query filters for the drizzle query API.
+								* @example
+								* ```ts
+								* author: t.relation("author", {
+								*  query: (_args, ctx) => ctx.abilities.users.filter("read").query.single,
+								* }),
+								* ´´´
+								*/
 								query: {
+									/**
+									* For find first calls
+									*/
 									single: {
 										extras: filters?.extras,
 										where: filters?.where
 									},
+									/**
+									* For find many calls
+									*/
 									many: {
 										extras: filters?.extras,
 										where: filters?.where,
@@ -494,6 +584,25 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 										}
 									}
 								},
+								/**
+								* Query filters for the drizzle SQL API as used in e.g. updates.
+								* @example
+								*
+								* ```ts
+								* await db
+								*	.update(schema.users)
+								*	.set({
+								*	  name: args.newName,
+								* 	})
+								*	.where(
+								*	  and(
+								*	    eq(schema.users.id, args.userId),
+								*	    ctx.abilities.users.filter("update").sql.where,
+								*	  ),
+								*	);
+								* ```
+								*
+								*/
 								sql: { get where() {
 									return sqlTransformedWhere();
 								} }
@@ -737,7 +846,7 @@ const createWhereArgImplementer = ({ db, schemaBuilder, enumImplementer }) => {
 //#region lib/client/client.ts
 const clientCreatorImplementer = ({ builtSchema }) => {
 	const clientCreator = async ({ apiUrl, outputPath, rumbleImportPath, useExternalUrqlClient, removeExisting, forceReactivity, autoIncludeIdField = false }) => {
-		if (process.env.NODE_ENV !== "development") console.warn(`Running rumble client generation in non development mode. Are you sure this is correct? Called from ${__filename} with arguments: ${JSON.stringify({
+		if (process.env.NODE_ENV !== "development") console.warn(`Running rumble client generation in non development mode. Are you sure this is correct? Called with arguments: ${JSON.stringify({
 			outputPath,
 			apiUrl,
 			rumbleImportPath,
@@ -1201,6 +1310,9 @@ const createPubSubInstance = ({ subscriptions }) => {
 			return `${SUBSCRIPTION_NOTIFIER_RUMBLE_PREFIX}/${tableName}${primaryKeyValue ? `/${primaryKeyValue}` : ""}/${actionKey}`;
 		}
 		return {
+			/**
+			* Call this when you want to register a subscription on an instance to this table
+			*/
 			registerOnInstance({ instance, action, primaryKeyValue }) {
 				const key = makePubSubKey({
 					tableName: table.toString(),
@@ -1209,6 +1321,9 @@ const createPubSubInstance = ({ subscriptions }) => {
 				});
 				instance.register(key);
 			},
+			/**
+			* Call this when you created an entity of this table
+			*/
 			created() {
 				const key = makePubSubKey({
 					tableName: table.toString(),
@@ -1216,6 +1331,9 @@ const createPubSubInstance = ({ subscriptions }) => {
 				});
 				return pubsub.publish(key);
 			},
+			/**
+			* Call this when you removed one or more entities of this table
+			*/
 			removed() {
 				const key = makePubSubKey({
 					tableName: table.toString(),
@@ -1223,6 +1341,9 @@ const createPubSubInstance = ({ subscriptions }) => {
 				});
 				return pubsub.publish(key);
 			},
+			/**
+			* Call this when you updated one or more entities of this table
+			*/
 			updated(primaryKeyValue) {
 				const keys = (Array.isArray(primaryKeyValue) ? primaryKeyValue : [primaryKeyValue]).map((primaryKeyValue) => makePubSubKey({
 					tableName: table.toString(),
@@ -1682,21 +1803,101 @@ export const db = drizzle(
 		});
 	};
 	return {
+		/**
+		* The ability builder. Use it to declare whats allowed for each entity in your DB.
+		*
+		* @example
+		*
+		* ```ts
+		* // users can edit themselves
+		abilityBuilder.users
+		.allow(["read", "update", "delete"])
+		.when(({ userId }) => ({ where: eq(schema.users.id, userId) }));
+		
+		// everyone can read posts
+		abilityBuilder.posts.allow("read");
+		*
+		* ```
+		*/
 		abilityBuilder,
+		/**
+		* The pothos schema builder. See https://pothos-graphql.dev/docs/plugins/drizzle
+		*/
 		schemaBuilder,
+		/**
+		* Creates the native yoga instance. Can be used to run an actual HTTP server.
+		*
+		* @example
+		*
+		* ```ts
+		* import { createServer } from "node:http";
+		* const server = createServer(createYoga());
+		* server.listen(3000, () => {
+		*   console.info("Visit http://localhost:3000/graphql");
+		* });
+		* ```
+		* https://the-guild.dev/graphql/yoga-server/docs#server
+		*/
 		createYoga,
+		/**
+		* Creates a sofa instance to offer a REST API.
+		*
+		* ```ts
+		* import express from "express";
+		*
+		* const app = express();
+		* const sofa = createSofa(...);
+		*
+		* app.use("/api", useSofa({ schema }));
+		* ```
+		* https://the-guild.dev/graphql/sofa-api/docs#usage
+		*/
 		createSofa,
+		/**
+		* A function for creating default objects for your schema
+		*/
 		object,
+		/**
+		* A function for creating where args to filter entities
+		*/
 		whereArg,
+		/**
+		* A function for creating order args to sort entities
+		*/
 		orderArg,
+		/**
+		* A function for creating default READ queries.
+		* Make sure the objects for the table you are creating the queries for are implemented
+		*/
 		query,
+		/**
+		* A function for creating a pubsub instance for a table. Use this to publish or subscribe events
+		*/
 		pubsub: makePubSubInstance,
+		/**
+		* A function to implement enums for graphql usage.
+		* The other helpers use this helper internally so in most cases you do not have to
+		* call this helper directly, unless you need the reference to an enum type
+		*/
 		enum_,
+		/**
+		* Create a client to consume a rumble graphql api at the specified location.
+		* Requires GraphQL, does not work with the SOFA REST API.
+		*/
 		clientCreator: clientCreatorImplementer({
 			...rumbleInput,
 			builtSchema
 		}),
-		countQuery
+		/**
+		* A function for creating count queries for your tables
+		*/
+		countQuery,
+		/**
+		* The generated GraphQL schema. You can use this for example to create a GraphQL server with a different library than Yoga or to generate types with codegen.
+		* When calling this function, the schema will be built for the first time and cached for later usage. So you can call this function multiple times without performance issues.
+		* After calling, you cannot adjust the schema via the schema builder
+		*/
+		buildSchema: builtSchema
 	};
 };
 //#endregion