@fitzzero/quickdraw-core 5.0.1 → 5.1.0

package/dist/testing/mock.d.ts

@@ -1,12 +1,12 @@
-import { A as AccessLevel, ae as ContractMap, J as AnyContract, ap as MethodName, al as InputOf, ar as OutputOf, af as EntityOf, ac as CollectionName, aw as ScopeOf, an as ItemOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, aa as ChannelName, a9 as ChannelInputOf, ag as EventName, ah as EventPayloadOf } from '../infer-Dw21kmLw.js';
+import { A as AccessLevel, ae as ContractMap, J as AnyContract, ap as MethodName, al as InputOf, ar as OutputOf, af as EntityOf, ac as CollectionName, aw as ScopeOf, an as ItemOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, aa as ChannelName, a9 as ChannelInputOf, ag as EventName, ah as EventPayloadOf } from '../infer-Teo1xpsd.js';
 import { QueryClient } from '@tanstack/react-query';
 import { ReactNode, ReactElement } from 'react';
-import { i as MethodMember, E as EntityMembers, C as CollectionMember, y as StreamMember, u as ChannelMember, v as EventMember, n as QuickdrawInvalidate } from '../clientTypes-DuZW_8mb.js';
-import { H as AdminMethodsOf } from '../admin-CBlTY0do.js';
+import { i as MethodMember, E as EntityMembers, C as CollectionMember, y as StreamMember, u as ChannelMember, v as EventMember, n as QuickdrawInvalidate } from '../clientTypes-Bc-G8n-U.js';
+import { H as AdminMethodsOf } from '../admin-DKwkIh5i.js';
 import { Q as QuickdrawError } from '../errors-S-bxEIBC.js';
 import '../keys-CqKkljVN.js';
-import '../adminSchemas-zji11V74.js';
-import '../envelope-nf5eGB-a.js';
+import '../adminSchemas-2DUA_hZ8.js';
+import '../envelope-Cp3YcVxC.js';
 
 /**
  * How a mocked method answers. Until one of the `mock*` setters runs, every

package/dist/testing/mock.js

@@ -1,10 +1,10 @@
 import {
   createMockClient
-} from "../chunk-HQ6WIRE2.js";
-import "../chunk-O2PWC2YW.js";
+} from "../chunk-3674EIRT.js";
+import "../chunk-KNDDCVQJ.js";
 import "../chunk-CDKG4TFA.js";
-import "../chunk-WVIRXYI4.js";
-import "../chunk-5YRQ26LF.js";
+import "../chunk-VJTFXHOK.js";
+import "../chunk-RT6OILOI.js";
 import "../chunk-47AEXVDM.js";
 import "../chunk-Z2LZ7IZ7.js";
 import "../chunk-YSWH776Y.js";

package/dist/{types-Bwg3kIEc.d.ts → types-Cu0vmx7c.d.ts}

@@ -1,4 +1,4 @@
-import { A as AccessLevel, ae as ContractMap } from './infer-Dw21kmLw.js';
+import { A as AccessLevel, ae as ContractMap } from './infer-Teo1xpsd.js';
 
 /**
  * Who is calling. A transport authenticates the connection or request and
@@ -48,6 +48,12 @@ type DbOf<T extends QuickdrawTypes> = T extends {
 type PrincipalOf<T extends QuickdrawTypes> = T extends {
     readonly principal: infer P extends Principal;
 } ? P : Principal;
+/**
+ * The kinds of the app's principal (`"user" | "agent"` when it declares
+ * `kind: "user" | "agent"`): what a `kinds` list names. Any string with the
+ * base {@link Principal}.
+ */
+type PrincipalKindOf<T extends QuickdrawTypes> = NonNullable<PrincipalOf<T>["kind"]>;
 /** The fields `initQuickdraw({ context })` adds to every handler's `ctx`. */
 type ContextExtensionOf<T extends QuickdrawTypes> = T extends {
     readonly context: infer Extension extends object;
@@ -63,4 +69,4 @@ type Transport = "socket" | "http" | "mcp" | "internal" | "legacy";
 /** A value, or a promise of it. */
 type MaybePromise<T> = T | PromiseLike<T>;
 
-export type { ContextExtensionOf as C, DbOf as D, MaybePromise as M, Principal as P, QuickdrawTypes as Q, Transport as T, McpContext as a, McpContextOf as b, PrincipalOf as c };
+export type { ContextExtensionOf as C, DbOf as D, MaybePromise as M, Principal as P, QuickdrawTypes as Q, Transport as T, McpContext as a, McpContextOf as b, PrincipalOf as c, PrincipalKindOf as d };

package/dist/utils/index.d.ts

@@ -1,7 +1,7 @@
 import { M as MethodQueryKey } from '../keys-CqKkljVN.js';
 export { C as CollectionQueryKey, E as EntityQueryKey, K as KEY_ROOT, b as MethodKeyPrefix, S as ServiceKeyPrefix, c as collectionKey, e as entityKey, m as methodKey, a as methodKeyPrefix, s as serviceKeyPrefix } from '../keys-CqKkljVN.js';
 import { QueryClient } from '@tanstack/react-query';
-import { ae as ContractMap, ap as MethodName, J as AnyContract, ao as KindOf, al as InputOf, ar as OutputOf } from '../infer-Dw21kmLw.js';
+import { ae as ContractMap, ap as MethodName, J as AnyContract, ao as KindOf, al as InputOf, ar as OutputOf } from '../infer-Teo1xpsd.js';
 
 /**
  * Format a currency value for display.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-core",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "Fast fullstack patterns for real-time applications with Socket.io and TanStack Query",
   "keywords": [
     "fullstack",

package/dist/chunk-5YRQ26LF.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/contract/collections.ts","../src/contract/realtime.ts"],"sourcesContent":["// Collection declarations for a contract (RFC 0003 section 7.1). A collection\n// is the rows of one service grouped by a scope value. Membership is declared\n// (a scope column or a junction table, plus an equality filter), never\n// computed by a function, so the framework knows which writes can move a row.\n// This replaces 4.1's `defineCollection({ resolveScopeId, checkScopeAccess,\n// snapshot, toItem })`.\n\nimport type { AccessLevel } from \"./access\";\n\n/** Page size of a collection snapshot when the collection sets no `limit`. */\nexport const DEFAULT_COLLECTION_LIMIT = 100;\n\n/** Largest page a client may ask for when the collection sets no `maxLimit`. */\nexport const DEFAULT_COLLECTION_MAX_LIMIT = 500;\n\n/**\n * A scope that comes from a junction table instead of a column on the row:\n * the rows of `model` link an entry (`entry` holds the row's id) to a scope\n * value (`scope`). For example, a chat appears in each member's list through\n * `via({ model: \"chatMember\", entry: \"chatId\", scope: \"userId\" })`.\n */\nexport interface ViaScope<\n  Model extends string = string,\n  Entry extends string = string,\n  Scope extends string = string,\n> {\n  readonly kind: \"via\";\n  readonly model: Model;\n  readonly entry: Entry;\n  readonly scope: Scope;\n  /**\n   * The item is computed from the junction (a member count): every junction\n   * write sends its entry again, whole, to each scope that still holds it.\n   * Without it a junction write only adds or removes the entry in the scope\n   * it links, so a count over the junction goes stale everywhere else.\n   */\n  readonly refreshEntry?: boolean;\n}\n\n/** What `via(...)` takes: the junction model, its entry and scope columns, and `refreshEntry`. */\nexport interface ViaOptions<\n  Model extends string = string,\n  Entry extends string = string,\n  Scope extends string = string,\n> {\n  /** The junction model, as the database client names it: `\"chatMember\"`. */\n  readonly model: Model;\n  /** The junction column holding the entry's id: `\"chatId\"`. */\n  readonly entry: Entry;\n  /** The junction column holding the scope value: `\"userId\"`. */\n  readonly scope: Scope;\n  /**\n   * Set when the item reads the junction, as a `memberCount` mapped from a\n   * relation count does: a junction create, update or delete then sends the\n   * entry again, as `updated`, to every scope that still holds it (one read\n   * of the entry's item per flush). Default `false`: a junction write adds\n   * or removes the entry for the scope it links, and nothing else.\n   */\n  readonly refreshEntry?: boolean;\n}\n\n/**\n * Declares a collection scope that comes from a junction table.\n *\n * @example\n * myChats: {\n *   scope: via({ model: \"chatMember\", entry: \"chatId\", scope: \"userId\", refreshEntry: true }),\n *   item: \"listItem\",\n *   order: [[\"id\", \"asc\"]],\n * }\n */\nexport function via<\n  const Model extends string,\n  const Entry extends string,\n  const Scope extends string,\n>(junction: ViaOptions<Model, Entry, Scope>): ViaScope<Model, Entry, Scope> {\n  return Object.freeze({\n    kind: \"via\",\n    model: junction.model,\n    entry: junction.entry,\n    scope: junction.scope,\n    ...(junction.refreshEntry === undefined ? {} : { refreshEntry: junction.refreshEntry }),\n  });\n}\n\nexport type SortDirection = \"asc\" | \"desc\";\n\n/**\n * Sort columns for the keyset cursor, ending in `id` so every row has a\n * unique position: `[[\"ordinal\", \"asc\"], [\"id\", \"asc\"]]`.\n */\nexport type OrderBy<Column extends string = string> = readonly [\n  ...(readonly [Column, SortDirection])[],\n  readonly [\"id\", SortDirection],\n];\n\n/** Who a view is evaluated for, on the client. */\nexport interface Viewer {\n  readonly userId: string;\n}\n\n/**\n * A view: a named pure predicate evaluated on the client over the index rows\n * of a scope (RFC 0003 section 7.5). `row` holds only `id` and the\n * collection's `index` fields, which the type enforces.\n */\nexport type ViewPredicate<Row> = (row: Row, who: Viewer) => boolean;\n\n/** The equality filter that decides membership, for example `{ archived: false }`. */\nexport interface CollectionWhere {\n  readonly [column: string]: string | number | boolean | null;\n}\n\n/** Any collection of any contract, as `defineContract` stores it. */\nexport interface CollectionDef {\n  /** A string column of the entity, or `via(...)` for a junction table. */\n  readonly scope: string | ViaScope;\n  /** The projection each item is sent as: `\"entity\"` or a named projection. */\n  readonly item: string;\n  /** Sort columns for the keyset cursor; the last one is `id`. */\n  readonly order: OrderBy;\n  /** Equality filter that decides membership. */\n  readonly where?: CollectionWhere | undefined;\n  /** Page size. Default {@link DEFAULT_COLLECTION_LIMIT}. */\n  readonly limit?: number | undefined;\n  /** Largest page a client may ask for. Default {@link DEFAULT_COLLECTION_MAX_LIMIT}. */\n  readonly maxLimit?: number | undefined;\n  /** Item fields sent for every member of the scope (RFC 0003 section 7.4). */\n  readonly index?: readonly string[] | undefined;\n  /** Named predicates over index rows. Requires `index`. */\n  readonly views?: { readonly [view: string]: ViewPredicate<never> } | undefined;\n  /** Level required on the scope's anchor row. Default `\"Read\"`, through the anchor's policy. */\n  readonly access?: AccessLevel | undefined;\n}\n","// Streams, channels and typed room events in a contract (RFC 0003 section\n// 12.5). A stream is server-to-client append-only data a subscriber receives\n// with a seed of recent items; a channel is fire-and-forget client-to-server\n// input (cursors, typing) behind a per-socket token bucket; an event is a\n// typed custom frame a handler sends to a room. 4.1 declared channels on the\n// service class (4.1 `src/server/BaseService.ts:915-942`) and typed room\n// events through the augmentable `QuickdrawEventMap`; here all three live in\n// the contract, so the client is typed from it.\n//\n// Methods, collections, streams, channels and events share one namespace:\n// the client exposes each as `qd.<service>.<name>`.\n\nimport type { AccessLevel } from \"./access\";\nimport type { AnyContract } from \"./defineContract\";\nimport type { StandardSchemaV1 } from \"./standardSchema\";\n\n/** The `scope` of a stream with one feed for the whole service: the default. */\nexport const GLOBAL_STREAM = \"global\";\n\n/** The most items a stream may keep per scope as the seed for new subscribers. */\nexport const STREAM_MAX_SEED = 1000;\n\n/** A channel's sustained rate when it declares none: messages per second per socket. */\nexport const CHANNEL_DEFAULT_RATE = 30;\n\n/**\n * The app room a stream's subscriber must be in (`access: { room }`): the\n * room's name, `{ prefix }` for any room whose name starts with it, or for a\n * scoped stream a function of the scope (`(worldId) => \\`world:${worldId}\\``).\n */\nexport type StreamRoom = string | RoomPrefix | ((scope: string) => string | null | undefined);\n\n/**\n * Who may subscribe to a stream (RFC 0003 section 4.1's forms, as data). A\n * scoped stream's scope value is the row an `entry` or `scope` form is about:\n * `{ entry: L }` needs level `L` on the row of this service whose id is the\n * scope, `{ scope: L, of }` level `L` on that row of `of`'s service.\n * `{ room }` opens it to the sockets in an app room a method joined them to\n * (signed in or not), as a channel's `requires: { room }` does its messages:\n * a socket that leaves the room, or is taken out of it, leaves the feed too.\n * A stream that declares none is closed: no client may subscribe.\n */\nexport type StreamAccess =\n  | \"public\"\n  | \"authenticated\"\n  | {\n      readonly service: AccessLevel;\n      readonly entry?: undefined;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly entry: AccessLevel;\n      readonly service?: AccessLevel;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly scope: AccessLevel;\n      readonly of: AnyContract;\n      readonly service?: undefined;\n      readonly entry?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly room: StreamRoom;\n      readonly service?: undefined;\n      readonly entry?: undefined;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n    };\n\n/** A server-to-client stream of append-only items (RFC 0003 section 12.5). */\nexport interface StreamDef<Item extends StandardSchemaV1 = StandardSchemaV1> {\n  /** One item's schema. Pushed items are checked against it before they are sent. */\n  readonly item: Item;\n  /**\n   * What a scope value is (`\"taskId\"`): the stream has one feed per scope.\n   * `\"global\"`, the default, makes one feed for the whole service.\n   */\n  readonly scope?: string;\n  /**\n   * How many of the latest items the server keeps per scope, in memory on\n   * each process, and sends a new subscriber first. Default 0; at most 1,000.\n   */\n  readonly seed?: number;\n  /** Send items volatile: dropped for a client whose connection is backed up. Default `false`. */\n  readonly volatile?: boolean;\n  /** Who may subscribe. Without it the stream is closed. */\n  readonly access?: StreamAccess;\n}\n\n/**\n * Where a channel requirement finds its row id or scope value in the parsed\n * payload: the name of a key holding a string, or a function of the payload.\n */\nexport type PayloadSelector = string | ((payload: never) => string | null | undefined);\n\n/**\n * Any app room whose name starts with `prefix` (`{ prefix: \"world:\" }`, a\n * game of many worlds): the sending socket passes when it is in one, and\n * the channel's handler gets the one it matched as `ctx.room`, so the\n * payload need not repeat which room it is for.\n */\nexport interface RoomPrefix {\n  readonly prefix: string;\n}\n\n/**\n * The app room a channel requirement names: the room itself (`\"world\"`, a\n * game's one world), a function of the parsed payload that returns it\n * (`(payload) => \\`lobby:${payload.lobbyId}\\``), or `{ prefix }`, any room\n * whose name starts with it (`{ prefix: \"world:\" }`). Unlike a\n * {@link PayloadSelector}, a string here is the room's name, not a payload\n * key. A name starting with `qd:` or `user:` is never an app room: a literal\n * one (or such a prefix) is refused when the contract is defined, and a\n * computed one drops the message.\n */\nexport type RoomSelector = string | ((payload: never) => string | null | undefined) | RoomPrefix;\n\n/**\n * What a channel message requires of the socket that sends it: a live\n * subscription (`qd:sub`) to the row of this service `entity` names, or\n * (`qd:col:sub`) to the scope of `collection` that `scope` names; or that\n * the socket is in the app room `room` names (or, for `{ prefix }`, in any\n * app room whose name starts with it), which a method called over that\n * same socket joined with `ctx.rooms.join` (a room another socket of the\n * user joined does not count, and a reconnected socket is in none until it\n * joins again). The handler gets the room that matched as `ctx.room`. Each\n * is checked in memory against the sending socket's own records, on the\n * node it is connected to. A message whose payload names none is dropped.\n */\nexport type ChannelRequires =\n  | {\n      readonly entity: PayloadSelector;\n      readonly collection?: undefined;\n      readonly scope?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly collection: string;\n      readonly scope: PayloadSelector;\n      readonly entity?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly room: RoomSelector;\n      readonly entity?: undefined;\n      readonly collection?: undefined;\n      readonly scope?: undefined;\n    };\n\n/** A client-to-server fire-and-forget channel (RFC 0003 section 12.5). */\nexport interface ChannelDef<Payload extends StandardSchemaV1 = StandardSchemaV1> {\n  /** One message's schema. A message that fails it is dropped. */\n  readonly payload: Payload;\n  /** Messages one socket may send per second, sustained. Default 30. */\n  readonly ratePerSecond?: number;\n  /** How many messages one socket may send at once. Default twice `ratePerSecond`. */\n  readonly burst?: number;\n  /** What the sender must already be subscribed to, or the app room it must be in. */\n  readonly requires?: ChannelRequires;\n}\n\n/** A typed custom room event, delivered as `qd:event` (RFC 0003 section 8.3). */\nexport interface EventDef<Payload extends StandardSchemaV1 = StandardSchemaV1> {\n  readonly payload: Payload;\n}\n\n/** True when a stream has one feed per scope value; false for a global stream. */\nexport function isScopedStream(def: Pick<StreamDef, \"scope\">): boolean {\n  return def.scope !== undefined && def.scope !== GLOBAL_STREAM;\n}\n"],"mappings":";AAUO,IAAM,2BAA2B;AAGjC,IAAM,+BAA+B;AA0DrC,SAAS,IAId,UAA0E;AAC1E,SAAO,OAAO,OAAO;AAAA,IACnB,MAAM;AAAA,IACN,OAAO,SAAS;AAAA,IAChB,OAAO,SAAS;AAAA,IAChB,OAAO,SAAS;AAAA,IAChB,GAAI,SAAS,iBAAiB,SAAY,CAAC,IAAI,EAAE,cAAc,SAAS,aAAa;AAAA,EACvF,CAAC;AACH;;;AClEO,IAAM,gBAAgB;AAGtB,IAAM,kBAAkB;AAGxB,IAAM,uBAAuB;AAqJ7B,SAAS,eAAe,KAAwC;AACrE,SAAO,IAAI,UAAU,UAAa,IAAI,UAAU;AAClD;","names":[]}