@m1212e/rumble 0.16.42 → 0.17.0

package/out/index.mjs

@@ -181,7 +181,7 @@ function mapNullFieldsToUndefined(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.16.42";
+var version = "0.17.0";
 //#endregion
 //#region lib/helpers/mergeFilters.ts
 function mergeFilters(filterA, filterB) {
@@ -347,6 +347,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];
@@ -357,24 +360,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 });
 					}
@@ -389,6 +426,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);
@@ -433,12 +474,27 @@ const createAbilityBuilder = ({ db, actions, defaultLimit, otel }) => {
 								return filters?.where ? 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,
@@ -448,16 +504,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,
@@ -466,6 +556,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();
 								} }
@@ -1173,6 +1282,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(),
@@ -1181,6 +1293,9 @@ const createPubSubInstance = ({ subscriptions }) => {
 				});
 				instance.register(key);
 			},
+			/**
+			* Call this when you created an entity of this table
+			*/
 			created() {
 				const key = makePubSubKey({
 					tableName: table.toString(),
@@ -1188,6 +1303,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(),
@@ -1195,6 +1313,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(),
@@ -1653,22 +1774,129 @@ export const db = drizzle(
 			}
 		});
 	};
+	const createWs = (implementation, args, ...rest) => {
+		return implementation({
+			...args,
+			schema: builtSchema(),
+			context
+		}, ...rest);
+	};
 	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: createYoga$1,
+		/**
+		* 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,
+		/**
+		* Creates a WebSocket server handler for GraphQL subscriptions.
+		* Pass the ws implementation function as the first argument and rumble will
+		* inject the schema and context automatically.
+		*
+		* @example
+		*
+		* ```ts
+		* // ws
+		* import { useServer } from "graphql-ws/use/ws";
+		* import { WebSocketServer } from "ws";
+		* const wss = new WebSocketServer({ port: 4000 });
+		* const disposable = createWs(useServer, { ... }, wss);
+		*
+		* // bun
+		* import { makeHandler } from "graphql-ws/use/bun";
+		* Bun.serve({ websocket: createWs(makeHandler, { ... }), ... });
+		* ```
+		*/
+		createWs,
+		/**
+		* 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