@geekmidas/constructs 10.0.0-alpha.5 → 10.0.0-alpha.50

package/dist/credential.mjs

@@ -1,8 +1,39 @@
 import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
 import { parseSchema } from "@geekmidas/schema/parser";
-
 //#region src/credential.ts
+/**
+* `Credential` — a third-party credential with a shape.
+*
+* The answer to the design's first open question, "where does `Secret` sit?".
+* It sits beside a secret rather than replacing it, because the two differ by
+* *lifecycle* and that is the only difference worth two kinds for: a secret is
+* generated and rotated by the platform and is one opaque string, while a
+* credential is issued by someone else, arrives with several fields, and is
+* worth validating on the way in.
+*
+* ```ts
+* export const stripe = new Credential('Stripe', {
+*   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),
+* });
+*
+* // in a handler — no await, already parsed and validated
+* services.stripe.secretKey
+* ```
+*
+* **Nothing about it is async at the call site**, which is the part that looks
+* like it should be hard and is not. `Service.register()` may return a promise
+* and `ServiceDiscovery` awaits every one before a handler runs, so fetching a
+* value and validating it — including when a StandardSchema's `~standard.validate`
+* returns a promise of its own — both happen inside that existing seam.
+*
+* **One key holding JSON, not one key per field.** That is the shape a secret
+* manager stores, and it is the only shape that works with an arbitrary
+* StandardSchema: the spec has no introspection API, so enumerating a schema's
+* fields means reaching into one library's internals (`.shape`) and being wrong
+* for every other.
+*/
 var Credential = class {
+	options;
 	id;
 	service;
 	/**
@@ -22,7 +53,7 @@ var Credential = class {
 		this.options = options;
 		const canonical = canonicalId(id);
 		this.id = canonical;
-		this.keys = { credential: provideKey(canonical, "credential") };
+		this.keys = { credentials: provideKey(canonical, "credentials") };
 		this.service = {
 			serviceName: serviceKey(canonical),
 			register: (registerOptions) => this.connect(registerOptions)
@@ -32,7 +63,7 @@ var Credential = class {
 		return [{
 			kind: "credential",
 			id: this.id,
-			provides: [this.keys.credential]
+			provides: [this.keys.credentials]
 		}];
 	}
 	connect(options) {
@@ -40,16 +71,28 @@ var Credential = class {
 		this.resolved ??= this.resolve(options);
 		return this.resolved;
 	}
-	async resolve(options) {
-		const { raw } = options.envParser.create((get) => ({ raw: get(this.keys.credential).string() })).parse();
-		try {
-			return await parseSchema(this.options.schema, decode(raw));
-		} catch (issues) {
-			throw new MalformedCredential(this.id, this.keys.credential, issues);
-		}
+	resolve(options) {
+		return readCredentials(this.id, this.keys.credentials, this.options.schema, options.envParser);
 	}
 };
 /**
+* A credentials key, read and validated against its schema.
+*
+* Shared with every construct that holds a third party's credentials — an
+* `ExternalApi` reads its own the same way — so the shape a stage stores and
+* the error a bad value raises are the same everywhere.
+*
+* @throws {MalformedCredential} when the value is not what the schema says.
+*/
+async function readCredentials(id, key, schema, envParser) {
+	const { raw } = envParser.create((get) => ({ raw: get(key).string() })).parse();
+	try {
+		return await parseSchema(schema, decode(raw));
+	} catch (issues) {
+		throw new MalformedCredential(id, key, issues);
+	}
+}
+/**
 * The raw environment value as the thing the schema should see.
 *
 * JSON when it is JSON, and the string itself when it is not — a credential
@@ -72,6 +115,9 @@ function decode(raw) {
 const JSON_SCHEME = "json:";
 /** A credential was set, and is not what its schema says it should be. */
 var MalformedCredential = class extends Error {
+	id;
+	key;
+	issues;
 	constructor(id, key, issues) {
 		super(`${key} is not a valid ${id} credential. It is validated where it is read, so this is the value that is set rather than the code that uses it: ${describe(issues)}`);
 		this.id = id;
@@ -88,7 +134,7 @@ function describe(issues) {
 		return path ? `${path}: ${issue.message}` : issue.message;
 	}).join("; ");
 }
-
 //#endregion
-export { Credential, MalformedCredential };
+export { Credential, MalformedCredential, readCredentials };
+
 //# sourceMappingURL=credential.mjs.map

package/dist/credential.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"credential.mjs","names":["id: ConstructName<TName>","options: CredentialOptions<TSchema>","options: ServiceRegisterOptions","raw: string","id: string","key: string","issues: unknown","issue: StandardSchemaV1.Issue"],"sources":["../src/credential.ts"],"sourcesContent":["/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { credential: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credential: provideKey(canonical, 'credential') };\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credential],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate async resolve(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<Value<TSchema>> {\n\t\tconst { raw } = options.envParser\n\t\t\t.create((get) => ({ raw: get(this.keys.credential).string() }))\n\t\t\t.parse();\n\n\t\ttry {\n\t\t\treturn await parseSchema(this.options.schema, decode(raw));\n\t\t} catch (issues) {\n\t\t\tthrow new MalformedCredential(this.id, this.keys.credential, issues);\n\t\t}\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n */\nfunction decode(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n"],"mappings":";;;;AAqEA,IAAa,aAAb,MAIA;CAQC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;;;;;;;;CASjB,AAAQ;CAER,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,YAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO,EAAE,YAAY,WAAW,WAAW,aAAa,CAAE;AAG/D,OAAK,UAAU;GACd,aAAa,WAAW,UAAU;GAClC,UAAU,CAAC,oBAAoB,KAAK,QAAQ,gBAAgB;EAC5D;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,UAAW;EAChC,CACD;CACD;CAED,AAAQ,QAAQC,SAA0D;AACzE,MAAI,KAAK,QAAQ,QAAS,QAAO,KAAK,QAAQ,QAAQ;AAEtD,OAAK,aAAa,KAAK,QAAQ,QAAQ;AAEvC,SAAO,KAAK;CACZ;CAED,MAAc,QACbA,SAC0B;EAC1B,MAAM,EAAE,KAAK,GAAG,QAAQ,UACtB,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,KAAK,KAAK,WAAW,CAAC,QAAQ,CAAE,GAAE,CAC9D,OAAO;AAET,MAAI;AACH,UAAO,MAAM,YAAY,KAAK,QAAQ,QAAQ,OAAO,IAAI,CAAC;EAC1D,SAAQ,QAAQ;AAChB,SAAM,IAAI,oBAAoB,KAAK,IAAI,KAAK,KAAK,YAAY;EAC7D;CACD;AACD;;;;;;;;AASD,SAAS,OAAOC,KAAsB;CACrC,MAAM,QAAQ,IAAI,WAAW,YAAY,GACtC,IAAI,MAAM,YAAY,OAAO,GAC7B;AAEH,KAAI;AACH,SAAO,KAAK,MAAM,MAAM;CACxB,QAAO;AACP,SAAO;CACP;AACD;;;;;;AAOD,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAC9C,YACUC,IACAC,KACAC,QACR;AACD,SACE,EAAE,IAAI,kBAAkB,GAAG,qHAEW,SAAS,OAAO,CAAC,EACxD;EARQ;EACA;EACA;AAOT,OAAK,OAAO;CACZ;AACD;;AAGD,SAAS,SAASA,QAAyB;AAC1C,MAAK,MAAM,QAAQ,OAAO,CAAE,QAAO,OAAO,OAAO;AAEjD,QAAO,OACL,IAAI,CAACC,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,IAAI,CAAC,mBACC,YAAY,WAAW,OAAO,QAAQ,IAAI,GAAG,OAAO,QAAQ,CACnE,CACA,KAAK,IAAI;AAEX,SAAO,QAAQ,EAAE,KAAK,IAAI,MAAM,QAAQ,IAAI,MAAM;CAClD,EAAC,CACD,KAAK,KAAK;AACZ"}
+{"version":3,"file":"credential.mjs","names":[],"sources":["../src/credential.ts"],"sourcesContent":["/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { credentials: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credentials: provideKey(canonical, 'credentials') };\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate resolve(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\treturn readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.schema,\n\t\t\toptions.envParser,\n\t\t);\n\t}\n}\n\n/**\n * A credentials key, read and validated against its schema.\n *\n * Shared with every construct that holds a third party's credentials — an\n * `ExternalApi` reads its own the same way — so the shape a stage stores and\n * the error a bad value raises are the same everywhere.\n *\n * @throws {MalformedCredential} when the value is not what the schema says.\n */\nexport async function readCredentials<TSchema extends StandardSchemaV1>(\n\tid: string,\n\tkey: string,\n\tschema: TSchema,\n\tenvParser: ServiceRegisterOptions['envParser'],\n): Promise<Value<TSchema>> {\n\tconst { raw } = envParser\n\t\t.create((get) => ({ raw: get(key).string() }))\n\t\t.parse();\n\n\ttry {\n\t\treturn await parseSchema(schema, decode(raw));\n\t} catch (issues) {\n\t\tthrow new MalformedCredential(id, key, issues);\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n */\nfunction decode(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,IAAa,aAAb,MAIA;CA4BmB;CApBlB;CACA;;;;;CAMA;;;;;;;;CASA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO,EAAE,aAAa,WAAW,WAAW,aAAa,EAAE;EAGhE,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,oBAAoB,KAAK,QAAQ,eAAe;EAC5D;CACD;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,WAAW;EACjC,CACD;CACD;CAEA,QAAgB,SAA0D;EACzE,IAAI,KAAK,QAAQ,SAAS,OAAO,KAAK,QAAQ,OAAO;EAErD,KAAK,aAAa,KAAK,QAAQ,OAAO;EAEtC,OAAO,KAAK;CACb;CAEA,QAAgB,SAA0D;EACzE,OAAO,gBACN,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,QACb,QAAQ,SACT;CACD;AACD;;;;;;;;;;AAWA,eAAsB,gBACrB,IACA,KACA,QACA,WAC0B;CAC1B,MAAM,EAAE,QAAQ,UACd,QAAQ,SAAS,EAAE,KAAK,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAC7C,MAAM;CAER,IAAI;EACH,OAAO,MAAM,YAAY,QAAQ,OAAO,GAAG,CAAC;CAC7C,SAAS,QAAQ;EAChB,MAAM,IAAI,oBAAoB,IAAI,KAAK,MAAM;CAC9C;AACD;;;;;;;;AASA,SAAS,OAAO,KAAsB;CACrC,MAAM,QAAQ,IAAI,WAAW,WAAW,IACrC,IAAI,MAAM,YAAY,MAAM,IAC5B;CAEH,IAAI;EACH,OAAO,KAAK,MAAM,KAAK;CACxB,QAAQ;EACP,OAAO;CACR;AACD;;;;;;AAOA,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CACA;CAHV,YACC,IACA,KACA,QACC;EACD,MACC,GAAG,IAAI,kBAAkB,GAAG,qHAEW,SAAS,MAAM,GACvD;EARS,KAAA,KAAA;EACA,KAAA,MAAA;EACA,KAAA,SAAA;EAOT,KAAK,OAAO;CACb;AACD;;AAGA,SAAS,SAAS,QAAyB;CAC1C,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,OAAO,OAAO,MAAM;CAEhD,OAAO,OACL,KAAK,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,KAAK,YACN,OAAO,YAAY,WAAW,OAAO,QAAQ,GAAG,IAAI,OAAO,OAAO,CACnE,CAAC,CACA,KAAK,GAAG;EAEV,OAAO,OAAO,GAAG,KAAK,IAAI,MAAM,YAAY,MAAM;CACnD,CAAC,CAAC,CACD,KAAK,IAAI;AACZ"}

package/dist/crons/index.cjs

@@ -1,14 +1,72 @@
-require('../construct-interface-BfjcOD_E.cjs');
-require('../Construct-CyS3RpTL.cjs');
-require('../functions-DJJA7VGc.cjs');
-require('../clone-Dy0cR2SZ.cjs');
-const require_CronBuilder = require('../CronBuilder-DyUr6nYz.cjs');
-
-//#region src/crons/index.ts
-const c = new require_CronBuilder.CronBuilder();
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_CronBuilder = require("../CronBuilder-BoHzlWU_.cjs");
+//#region src/crons/schedule.ts
+/**
+* A schedule a cron runner can take, as standard five-field cron.
+*
+* `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already
+* five-field cron and unwraps; `rate(n unit)` is an interval, and an interval
+* is not a schedule — it says how often, where cron says when.
+*
+* Most intervals still have an exact cron equivalent, because they divide their
+* unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that
+* is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field
+* that means "every seven hours" — `*​/7` in the hour field fires at 0, 7, 14
+* and 21 and then starts over at midnight, so the gap between the last firing
+* of one day and the first of the next is three hours rather than seven.
+*
+* Those are refused rather than rounded. A job that runs at the wrong hour is
+* far harder to notice than one that refused to build, and a schedule quietly
+* adjusted by the framework is a bug nobody goes looking for.
+*/
+var UnrepresentableSchedule = class extends Error {
+	schedule;
+	constructor(schedule, reason) {
+		super(`\`${schedule}\` has no exact cron equivalent: ${reason}.\n\nCron says *when*, not *how often*, so an interval is only exact when it divides its unit evenly.
+Write the schedule you mean instead — \`cron(0 */6 * * *)\` for every sixth hour, say — or pick an interval that divides: minutes into 60, hours into 24.`);
+		this.schedule = schedule;
+		this.name = "UnrepresentableSchedule";
+	}
+};
+/** Units `rate(…)` accepts, singular or plural. */
+const UNITS = [
+	"minute",
+	"hour",
+	"day"
+];
+/**
+* Standard five-field cron for a schedule expression.
+*
+* @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.
+*/
+function toCronExpression(schedule) {
+	const cron = /^cron\((.+)\)$/.exec(schedule);
+	if (cron?.[1]) return cron[1].trim();
+	const rate = /^rate\(\s*(\d+)\s+(\w+?)s?\s*\)$/.exec(schedule);
+	if (!rate) throw new UnrepresentableSchedule(schedule, "it is neither `cron(…)` nor `rate(n unit)`");
+	const every = Number(rate[1]);
+	const unit = rate[2];
+	/* c8 ignore next */ if (!unit) throw new UnrepresentableSchedule(schedule, "no unit");
+	if (!UNITS.includes(unit)) throw new UnrepresentableSchedule(schedule, `\`${unit}\` is not one of ${UNITS.join(", ")}`);
+	if (every < 1) throw new UnrepresentableSchedule(schedule, "an interval must be at least 1");
+	switch (unit) {
+		case "minute":
+			if (every === 1) return "* * * * *";
+			if (60 % every !== 0) throw new UnrepresentableSchedule(schedule, `${every} does not divide 60, so the interval would reset at the top of each hour`);
+			return `*/${every} * * * *`;
+		case "hour":
+			if (every === 1) return "0 * * * *";
+			if (24 % every !== 0) throw new UnrepresentableSchedule(schedule, `${every} does not divide 24, so the interval would reset at midnight`);
+			return `0 */${every} * * *`;
+		case "day":
+			if (every === 1) return "0 0 * * *";
+			throw new UnrepresentableSchedule(schedule, "day-of-month restarts every month, so no multi-day interval is even");
+	}
+}
 //#endregion
 exports.Cron = require_CronBuilder.Cron;
 exports.CronBuilder = require_CronBuilder.CronBuilder;
-exports.c = c;
+exports.UnrepresentableSchedule = UnrepresentableSchedule;
+exports.toCronExpression = toCronExpression;
+
 //# sourceMappingURL=index.cjs.map

package/dist/crons/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["CronBuilder"],"sources":["../../src/crons/index.ts"],"sourcesContent":["export {\n\tCron,\n\ttype CronExpression,\n\ttype RateExpression,\n\ttype ScheduleExpression,\n} from './Cron';\nexport { CronBuilder } from './CronBuilder';\n\nimport { CronBuilder } from './CronBuilder';\n\nexport const c = new CronBuilder();\n"],"mappings":";;;;;;;AAUA,MAAa,IAAI,IAAIA"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/crons/schedule.ts"],"sourcesContent":["import type { ScheduleExpression } from './Cron';\n\n/**\n * A schedule a cron runner can take, as standard five-field cron.\n *\n * `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already\n * five-field cron and unwraps; `rate(n unit)` is an interval, and an interval\n * is not a schedule — it says how often, where cron says when.\n *\n * Most intervals still have an exact cron equivalent, because they divide their\n * unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that\n * is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field\n * that means \"every seven hours\" — `*​/7` in the hour field fires at 0, 7, 14\n * and 21 and then starts over at midnight, so the gap between the last firing\n * of one day and the first of the next is three hours rather than seven.\n *\n * Those are refused rather than rounded. A job that runs at the wrong hour is\n * far harder to notice than one that refused to build, and a schedule quietly\n * adjusted by the framework is a bug nobody goes looking for.\n */\nexport class UnrepresentableSchedule extends Error {\n\tconstructor(\n\t\treadonly schedule: string,\n\t\treason: string,\n\t) {\n\t\tsuper(\n\t\t\t`\\`${schedule}\\` has no exact cron equivalent: ${reason}.\\n\\n` +\n\t\t\t\t'Cron says *when*, not *how often*, so an interval is only exact when ' +\n\t\t\t\t'it divides its unit evenly.\\n' +\n\t\t\t\t'Write the schedule you mean instead — `cron(0 */6 * * *)` for every ' +\n\t\t\t\t'sixth hour, say — or pick an interval that divides: minutes into 60, ' +\n\t\t\t\t'hours into 24.',\n\t\t);\n\t\tthis.name = 'UnrepresentableSchedule';\n\t}\n}\n\n/** Units `rate(…)` accepts, singular or plural. */\nconst UNITS = ['minute', 'hour', 'day'] as const;\ntype Unit = (typeof UNITS)[number];\n\n/**\n * Standard five-field cron for a schedule expression.\n *\n * @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.\n */\nexport function toCronExpression(schedule: ScheduleExpression): string {\n\tconst cron = /^cron\\((.+)\\)$/.exec(schedule);\n\tif (cron?.[1]) return cron[1].trim();\n\n\tconst rate = /^rate\\(\\s*(\\d+)\\s+(\\w+?)s?\\s*\\)$/.exec(schedule);\n\tif (!rate) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t'it is neither `cron(…)` nor `rate(n unit)`',\n\t\t);\n\t}\n\n\tconst every = Number(rate[1]);\n\tconst unit = rate[2] as Unit;\n\t/* c8 ignore next */ if (!unit)\n\t\tthrow new UnrepresentableSchedule(schedule, 'no unit');\n\n\tif (!UNITS.includes(unit)) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t`\\`${unit}\\` is not one of ${UNITS.join(', ')}`,\n\t\t);\n\t}\n\n\tif (every < 1) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t'an interval must be at least 1',\n\t\t);\n\t}\n\n\tswitch (unit) {\n\t\tcase 'minute':\n\t\t\tif (every === 1) return '* * * * *';\n\t\t\tif (60 % every !== 0) {\n\t\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\t\tschedule,\n\t\t\t\t\t`${every} does not divide 60, so the interval would reset at the top of each hour`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn `*/${every} * * * *`;\n\n\t\tcase 'hour':\n\t\t\tif (every === 1) return '0 * * * *';\n\t\t\tif (24 % every !== 0) {\n\t\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\t\tschedule,\n\t\t\t\t\t`${every} does not divide 24, so the interval would reset at midnight`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn `0 */${every} * * *`;\n\n\t\tcase 'day':\n\t\t\tif (every === 1) return '0 0 * * *';\n\t\t\t// `*/n` in day-of-month restarts on the 1st, so a 2-day interval fires\n\t\t\t// on the 1st and 3rd of a 31-day month and then again on the 1st — one\n\t\t\t// day later, not two. No month length makes that come out even.\n\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\tschedule,\n\t\t\t\t'day-of-month restarts every month, so no multi-day interval is even',\n\t\t\t);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoBA,IAAa,0BAAb,cAA6C,MAAM;CAExC;CADV,YACC,UACA,QACC;EACD,MACC,KAAK,SAAS,mCAAmC,OAAO;0JAMzD;EAVS,KAAA,WAAA;EAWT,KAAK,OAAO;CACb;AACD;;AAGA,MAAM,QAAQ;CAAC;CAAU;CAAQ;AAAK;;;;;;AAQtC,SAAgB,iBAAiB,UAAsC;CACtE,MAAM,OAAO,iBAAiB,KAAK,QAAQ;CAC3C,IAAI,OAAO,IAAI,OAAO,KAAK,EAAE,CAAC,KAAK;CAEnC,MAAM,OAAO,mCAAmC,KAAK,QAAQ;CAC7D,IAAI,CAAC,MACJ,MAAM,IAAI,wBACT,UACA,4CACD;CAGD,MAAM,QAAQ,OAAO,KAAK,EAAE;CAC5B,MAAM,OAAO,KAAK;sBACG,IAAI,CAAC,MACzB,MAAM,IAAI,wBAAwB,UAAU,SAAS;CAEtD,IAAI,CAAC,MAAM,SAAS,IAAI,GACvB,MAAM,IAAI,wBACT,UACA,KAAK,KAAK,mBAAmB,MAAM,KAAK,IAAI,GAC7C;CAGD,IAAI,QAAQ,GACX,MAAM,IAAI,wBACT,UACA,gCACD;CAGD,QAAQ,MAAR;EACC,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GACxB,IAAI,KAAK,UAAU,GAClB,MAAM,IAAI,wBACT,UACA,GAAG,MAAM,yEACV;GAED,OAAO,KAAK,MAAM;EAEnB,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GACxB,IAAI,KAAK,UAAU,GAClB,MAAM,IAAI,wBACT,UACA,GAAG,MAAM,6DACV;GAED,OAAO,OAAO,MAAM;EAErB,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GAIxB,MAAM,IAAI,wBACT,UACA,qEACD;CACF;AACD"}

package/dist/crons/index.d.cts

@@ -1,16 +1,34 @@
-import "../Construct-C0ijr2qp.cjs";
-import "../index-AIfVzkhi.cjs";
-import "../construct-interface-D9d4Gm4p.cjs";
-import { Cron, CronExpression, RateExpression, ScheduleExpression } from "../Cron-B2OFsfDM.cjs";
-import { CronBuilder } from "../CronBuilder-LSJMfqnq.cjs";
-import * as _geekmidas_logger2 from "@geekmidas/logger";
-import * as _geekmidas_schema0 from "@geekmidas/schema";
-import * as _geekmidas_services1 from "@geekmidas/services";
-
-//#region src/crons/index.d.ts
-declare const c: CronBuilder<_geekmidas_schema0.ComposableStandardSchema, _geekmidas_services1.Service<string, unknown>[], _geekmidas_logger2.Logger, undefined, undefined, string, undefined, string>;
-//# sourceMappingURL=index.d.ts.map
-
+import { i as ScheduleExpression, n as CronExpression, r as RateExpression, t as Cron } from "../Cron-DI3nKoic.cjs";
+import { t as CronBuilder } from "../CronBuilder-g1lZLWyG.cjs";
+//#region src/crons/schedule.d.ts
+/**
+ * A schedule a cron runner can take, as standard five-field cron.
+ *
+ * `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already
+ * five-field cron and unwraps; `rate(n unit)` is an interval, and an interval
+ * is not a schedule — it says how often, where cron says when.
+ *
+ * Most intervals still have an exact cron equivalent, because they divide their
+ * unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that
+ * is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field
+ * that means "every seven hours" — `*​/7` in the hour field fires at 0, 7, 14
+ * and 21 and then starts over at midnight, so the gap between the last firing
+ * of one day and the first of the next is three hours rather than seven.
+ *
+ * Those are refused rather than rounded. A job that runs at the wrong hour is
+ * far harder to notice than one that refused to build, and a schedule quietly
+ * adjusted by the framework is a bug nobody goes looking for.
+ */
+export declare class UnrepresentableSchedule extends Error {
+  readonly schedule: string;
+  constructor(schedule: string, reason: string);
+}
+/**
+ * Standard five-field cron for a schedule expression.
+ *
+ * @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.
+ */
+export declare function toCronExpression(schedule: ScheduleExpression): string;
 //#endregion
-export { Cron, CronBuilder, CronExpression, RateExpression, ScheduleExpression, c };
+export { Cron, CronBuilder, type CronExpression, type RateExpression, type ScheduleExpression };
 //# sourceMappingURL=index.d.cts.map

package/dist/crons/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/crons/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAUa,GAAC,YAAoB,kBAAA,CAApB,wBAAA,EAAA,oBAAA,CAAA,4BAAA,kBAAA,CAAA,MAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/crons/schedule.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;qBAoBa,gCAAgC;WAElC;EADV,YACU,kBACT;;;;;;;wBAuBc,iBAAiB,UAAU"}

package/dist/crons/index.d.mts

@@ -1,16 +1,34 @@
-import "../Construct-Ct8nalEi.mjs";
-import "../index-D3zjrwjr.mjs";
-import "../construct-interface-g5GM5pwR.mjs";
-import { Cron, CronExpression, RateExpression, ScheduleExpression } from "../Cron-CqEbBbwH.mjs";
-import { CronBuilder } from "../CronBuilder-Bg-9h2cc.mjs";
-import * as _geekmidas_services23 from "@geekmidas/services";
-import * as _geekmidas_logger24 from "@geekmidas/logger";
-import * as _geekmidas_schema22 from "@geekmidas/schema";
-
-//#region src/crons/index.d.ts
-declare const c: CronBuilder<_geekmidas_schema22.ComposableStandardSchema, _geekmidas_services23.Service<string, unknown>[], _geekmidas_logger24.Logger, undefined, undefined, string, undefined, string>;
-//# sourceMappingURL=index.d.ts.map
-
+import { i as ScheduleExpression, n as CronExpression, r as RateExpression, t as Cron } from "../Cron-uYAHPnp7.mjs";
+import { t as CronBuilder } from "../CronBuilder-DaSUm2Na.mjs";
+//#region src/crons/schedule.d.ts
+/**
+ * A schedule a cron runner can take, as standard five-field cron.
+ *
+ * `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already
+ * five-field cron and unwraps; `rate(n unit)` is an interval, and an interval
+ * is not a schedule — it says how often, where cron says when.
+ *
+ * Most intervals still have an exact cron equivalent, because they divide their
+ * unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that
+ * is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field
+ * that means "every seven hours" — `*​/7` in the hour field fires at 0, 7, 14
+ * and 21 and then starts over at midnight, so the gap between the last firing
+ * of one day and the first of the next is three hours rather than seven.
+ *
+ * Those are refused rather than rounded. A job that runs at the wrong hour is
+ * far harder to notice than one that refused to build, and a schedule quietly
+ * adjusted by the framework is a bug nobody goes looking for.
+ */
+export declare class UnrepresentableSchedule extends Error {
+  readonly schedule: string;
+  constructor(schedule: string, reason: string);
+}
+/**
+ * Standard five-field cron for a schedule expression.
+ *
+ * @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.
+ */
+export declare function toCronExpression(schedule: ScheduleExpression): string;
 //#endregion
-export { Cron, CronBuilder, CronExpression, RateExpression, ScheduleExpression, c };
+export { Cron, CronBuilder, type CronExpression, type RateExpression, type ScheduleExpression };
 //# sourceMappingURL=index.d.mts.map

package/dist/crons/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/crons/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAUa,GAAC,YAAoB,mBAAA,CAApB,wBAAA,EAAA,qBAAA,CAAA,4BAAA,mBAAA,CAAA,MAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/crons/schedule.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;qBAoBa,gCAAgC;WAElC;EADV,YACU,kBACT;;;;;;;wBAuBc,iBAAiB,UAAU"}

package/dist/crons/index.mjs

@@ -1,12 +1,68 @@
-import "../Construct-BD5neF7w.mjs";
-import "../construct-interface-Z4CpS8tK.mjs";
-import "../functions-Ck21Uyq0.mjs";
-import "../clone-DblgEZZa.mjs";
-import { Cron, CronBuilder } from "../CronBuilder-CdibiHNB.mjs";
-
-//#region src/crons/index.ts
-const c = new CronBuilder();
-
+import { n as Cron, t as CronBuilder } from "../CronBuilder-CCgt0wCE.mjs";
+//#region src/crons/schedule.ts
+/**
+* A schedule a cron runner can take, as standard five-field cron.
+*
+* `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already
+* five-field cron and unwraps; `rate(n unit)` is an interval, and an interval
+* is not a schedule — it says how often, where cron says when.
+*
+* Most intervals still have an exact cron equivalent, because they divide their
+* unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that
+* is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field
+* that means "every seven hours" — `*​/7` in the hour field fires at 0, 7, 14
+* and 21 and then starts over at midnight, so the gap between the last firing
+* of one day and the first of the next is three hours rather than seven.
+*
+* Those are refused rather than rounded. A job that runs at the wrong hour is
+* far harder to notice than one that refused to build, and a schedule quietly
+* adjusted by the framework is a bug nobody goes looking for.
+*/
+var UnrepresentableSchedule = class extends Error {
+	schedule;
+	constructor(schedule, reason) {
+		super(`\`${schedule}\` has no exact cron equivalent: ${reason}.\n\nCron says *when*, not *how often*, so an interval is only exact when it divides its unit evenly.
+Write the schedule you mean instead — \`cron(0 */6 * * *)\` for every sixth hour, say — or pick an interval that divides: minutes into 60, hours into 24.`);
+		this.schedule = schedule;
+		this.name = "UnrepresentableSchedule";
+	}
+};
+/** Units `rate(…)` accepts, singular or plural. */
+const UNITS = [
+	"minute",
+	"hour",
+	"day"
+];
+/**
+* Standard five-field cron for a schedule expression.
+*
+* @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.
+*/
+function toCronExpression(schedule) {
+	const cron = /^cron\((.+)\)$/.exec(schedule);
+	if (cron?.[1]) return cron[1].trim();
+	const rate = /^rate\(\s*(\d+)\s+(\w+?)s?\s*\)$/.exec(schedule);
+	if (!rate) throw new UnrepresentableSchedule(schedule, "it is neither `cron(…)` nor `rate(n unit)`");
+	const every = Number(rate[1]);
+	const unit = rate[2];
+	/* c8 ignore next */ if (!unit) throw new UnrepresentableSchedule(schedule, "no unit");
+	if (!UNITS.includes(unit)) throw new UnrepresentableSchedule(schedule, `\`${unit}\` is not one of ${UNITS.join(", ")}`);
+	if (every < 1) throw new UnrepresentableSchedule(schedule, "an interval must be at least 1");
+	switch (unit) {
+		case "minute":
+			if (every === 1) return "* * * * *";
+			if (60 % every !== 0) throw new UnrepresentableSchedule(schedule, `${every} does not divide 60, so the interval would reset at the top of each hour`);
+			return `*/${every} * * * *`;
+		case "hour":
+			if (every === 1) return "0 * * * *";
+			if (24 % every !== 0) throw new UnrepresentableSchedule(schedule, `${every} does not divide 24, so the interval would reset at midnight`);
+			return `0 */${every} * * *`;
+		case "day":
+			if (every === 1) return "0 0 * * *";
+			throw new UnrepresentableSchedule(schedule, "day-of-month restarts every month, so no multi-day interval is even");
+	}
+}
 //#endregion
-export { Cron, CronBuilder, c };
+export { Cron, CronBuilder, UnrepresentableSchedule, toCronExpression };
+
 //# sourceMappingURL=index.mjs.map

package/dist/crons/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/crons/index.ts"],"sourcesContent":["export {\n\tCron,\n\ttype CronExpression,\n\ttype RateExpression,\n\ttype ScheduleExpression,\n} from './Cron';\nexport { CronBuilder } from './CronBuilder';\n\nimport { CronBuilder } from './CronBuilder';\n\nexport const c = new CronBuilder();\n"],"mappings":";;;;;;;AAUA,MAAa,IAAI,IAAI"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/crons/schedule.ts"],"sourcesContent":["import type { ScheduleExpression } from './Cron';\n\n/**\n * A schedule a cron runner can take, as standard five-field cron.\n *\n * `ScheduleExpression` has two spellings. `cron(m h dom mon dow)` is already\n * five-field cron and unwraps; `rate(n unit)` is an interval, and an interval\n * is not a schedule — it says how often, where cron says when.\n *\n * Most intervals still have an exact cron equivalent, because they divide their\n * unit evenly: `rate(5 minutes)` is every fifth minute of every hour, and that\n * is `*​/5 * * * *` precisely. `rate(7 hours)` has none. There is no cron field\n * that means \"every seven hours\" — `*​/7` in the hour field fires at 0, 7, 14\n * and 21 and then starts over at midnight, so the gap between the last firing\n * of one day and the first of the next is three hours rather than seven.\n *\n * Those are refused rather than rounded. A job that runs at the wrong hour is\n * far harder to notice than one that refused to build, and a schedule quietly\n * adjusted by the framework is a bug nobody goes looking for.\n */\nexport class UnrepresentableSchedule extends Error {\n\tconstructor(\n\t\treadonly schedule: string,\n\t\treason: string,\n\t) {\n\t\tsuper(\n\t\t\t`\\`${schedule}\\` has no exact cron equivalent: ${reason}.\\n\\n` +\n\t\t\t\t'Cron says *when*, not *how often*, so an interval is only exact when ' +\n\t\t\t\t'it divides its unit evenly.\\n' +\n\t\t\t\t'Write the schedule you mean instead — `cron(0 */6 * * *)` for every ' +\n\t\t\t\t'sixth hour, say — or pick an interval that divides: minutes into 60, ' +\n\t\t\t\t'hours into 24.',\n\t\t);\n\t\tthis.name = 'UnrepresentableSchedule';\n\t}\n}\n\n/** Units `rate(…)` accepts, singular or plural. */\nconst UNITS = ['minute', 'hour', 'day'] as const;\ntype Unit = (typeof UNITS)[number];\n\n/**\n * Standard five-field cron for a schedule expression.\n *\n * @throws {UnrepresentableSchedule} when a `rate(…)` has no exact equivalent.\n */\nexport function toCronExpression(schedule: ScheduleExpression): string {\n\tconst cron = /^cron\\((.+)\\)$/.exec(schedule);\n\tif (cron?.[1]) return cron[1].trim();\n\n\tconst rate = /^rate\\(\\s*(\\d+)\\s+(\\w+?)s?\\s*\\)$/.exec(schedule);\n\tif (!rate) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t'it is neither `cron(…)` nor `rate(n unit)`',\n\t\t);\n\t}\n\n\tconst every = Number(rate[1]);\n\tconst unit = rate[2] as Unit;\n\t/* c8 ignore next */ if (!unit)\n\t\tthrow new UnrepresentableSchedule(schedule, 'no unit');\n\n\tif (!UNITS.includes(unit)) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t`\\`${unit}\\` is not one of ${UNITS.join(', ')}`,\n\t\t);\n\t}\n\n\tif (every < 1) {\n\t\tthrow new UnrepresentableSchedule(\n\t\t\tschedule,\n\t\t\t'an interval must be at least 1',\n\t\t);\n\t}\n\n\tswitch (unit) {\n\t\tcase 'minute':\n\t\t\tif (every === 1) return '* * * * *';\n\t\t\tif (60 % every !== 0) {\n\t\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\t\tschedule,\n\t\t\t\t\t`${every} does not divide 60, so the interval would reset at the top of each hour`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn `*/${every} * * * *`;\n\n\t\tcase 'hour':\n\t\t\tif (every === 1) return '0 * * * *';\n\t\t\tif (24 % every !== 0) {\n\t\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\t\tschedule,\n\t\t\t\t\t`${every} does not divide 24, so the interval would reset at midnight`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn `0 */${every} * * *`;\n\n\t\tcase 'day':\n\t\t\tif (every === 1) return '0 0 * * *';\n\t\t\t// `*/n` in day-of-month restarts on the 1st, so a 2-day interval fires\n\t\t\t// on the 1st and 3rd of a 31-day month and then again on the 1st — one\n\t\t\t// day later, not two. No month length makes that come out even.\n\t\t\tthrow new UnrepresentableSchedule(\n\t\t\t\tschedule,\n\t\t\t\t'day-of-month restarts every month, so no multi-day interval is even',\n\t\t\t);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoBA,IAAa,0BAAb,cAA6C,MAAM;CAExC;CADV,YACC,UACA,QACC;EACD,MACC,KAAK,SAAS,mCAAmC,OAAO;0JAMzD;EAVS,KAAA,WAAA;EAWT,KAAK,OAAO;CACb;AACD;;AAGA,MAAM,QAAQ;CAAC;CAAU;CAAQ;AAAK;;;;;;AAQtC,SAAgB,iBAAiB,UAAsC;CACtE,MAAM,OAAO,iBAAiB,KAAK,QAAQ;CAC3C,IAAI,OAAO,IAAI,OAAO,KAAK,EAAE,CAAC,KAAK;CAEnC,MAAM,OAAO,mCAAmC,KAAK,QAAQ;CAC7D,IAAI,CAAC,MACJ,MAAM,IAAI,wBACT,UACA,4CACD;CAGD,MAAM,QAAQ,OAAO,KAAK,EAAE;CAC5B,MAAM,OAAO,KAAK;sBACG,IAAI,CAAC,MACzB,MAAM,IAAI,wBAAwB,UAAU,SAAS;CAEtD,IAAI,CAAC,MAAM,SAAS,IAAI,GACvB,MAAM,IAAI,wBACT,UACA,KAAK,KAAK,mBAAmB,MAAM,KAAK,IAAI,GAC7C;CAGD,IAAI,QAAQ,GACX,MAAM,IAAI,wBACT,UACA,gCACD;CAGD,QAAQ,MAAR;EACC,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GACxB,IAAI,KAAK,UAAU,GAClB,MAAM,IAAI,wBACT,UACA,GAAG,MAAM,yEACV;GAED,OAAO,KAAK,MAAM;EAEnB,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GACxB,IAAI,KAAK,UAAU,GAClB,MAAM,IAAI,wBACT,UACA,GAAG,MAAM,6DACV;GAED,OAAO,OAAO,MAAM;EAErB,KAAK;GACJ,IAAI,UAAU,GAAG,OAAO;GAIxB,MAAM,IAAI,wBACT,UACA,qEACD;CACF;AACD"}

package/dist/database/kysely.cjs

@@ -1,10 +1,23 @@
-const require_chunk = require('../chunk-DWy1uDak.cjs');
-const require_cache = require('../cache-3WSvAulx.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const kysely = require_chunk.__toESM(require("kysely"));
-const pg = require_chunk.__toESM(require("pg"));
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("../rolldown-runtime-y5ARvAq5.cjs");
+const require_cache = require("../cache.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let kysely = require("kysely");
+let pg = require("pg");
+pg = require_rolldown_runtime.__toESM(pg, 1);
 //#region src/database/kysely.ts
+/**
+* `KyselyDatabase` — a declared Postgres database, typed by its schema.
+*
+* It declares a logical database, a schema, and the roles that reach it, and
+* hands back a Kysely client built from the one URL the adapter supplied. It
+* names no cloud: `--target=aws` fills that URL from RDS, local dev from the
+* Postgres container.
+*
+* Transactions and RLS context are the execution wrapper's job — it opens the
+* transaction and puts it in `ctx.db`. This construct does not resolve
+* connections per request.
+*/
 /** The schema a database uses when it does not say otherwise. */
 const DEFAULT_SCHEMA = "app";
 /**
@@ -15,6 +28,7 @@ const DEFAULT_SCHEMA = "app";
 * through `.database()`, which infers from the service.
 */
 var KyselyDatabase = class KyselyDatabase {
+	options;
 	id;
 	service;
 	/**
@@ -28,18 +42,18 @@ var KyselyDatabase = class KyselyDatabase {
 	derivedFrom;
 	constructor(id, options = {}, derivedFrom) {
 		this.options = options;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
 		this.id = canonical;
 		this.config = {
-			url: (0, __geekmidas_manifest.provideKey)(canonical, "url"),
-			ownerUrl: (0, __geekmidas_manifest.provideKey)(canonical, "ownerUrl")
+			url: (0, _geekmidas_manifest.provideKey)(canonical, "url"),
+			ownerUrl: (0, _geekmidas_manifest.provideKey)(canonical, "ownerUrl")
 		};
 		this.schemaName = options.schema ?? DEFAULT_SCHEMA;
 		this.roles = options.roles ?? true;
-		this.version = options.version ?? __geekmidas_manifest.DEFAULT_POSTGRES_VERSION;
+		this.version = options.version ?? _geekmidas_manifest.DEFAULT_POSTGRES_VERSION;
 		this.derivedFrom = derivedFrom;
 		this.service = {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
 			register: (registerOptions) => this.connect(registerOptions)
 		};
 	}
@@ -139,18 +153,29 @@ var KyselyDatabase = class KyselyDatabase {
 	*/
 	get owner() {
 		return {
-			serviceName: `${(0, __geekmidas_manifest.serviceKey)(this.id)}Owner`,
+			serviceName: `${(0, _geekmidas_manifest.serviceKey)(this.id)}Owner`,
 			register: (options) => this.connect(options, { owner: true })
 		};
 	}
+	/**
+	* What this database's clients are built with besides a dialect — the
+	* plugins and logging it was declared with.
+	*
+	* Public so that whatever opens a connection to it outside \`connect()\` —
+	* a test's transaction — builds the same client. A test that dropped the
+	* plugins would write \`createdAt\` where production writes \`created_at\`.
+	*/
+	get clientConfig() {
+		const { schema: _schema, roles: _roles, version: _version, ...kysely$1 } = this.options;
+		return kysely$1;
+	}
 	async connect(options, as = {}) {
 		const { url, ownerUrl } = options.envParser.create((get) => ({
 			url: get(this.config.url).string(),
 			ownerUrl: get(this.config.ownerUrl).string().optional()
 		})).parse();
-		const { schema: _schema, roles: _roles,...kysely$1 } = this.options;
 		return new kysely.Kysely({
-			...kysely$1,
+			...this.clientConfig,
 			dialect: new kysely.PostgresDialect({ pool: pool(as.owner ? ownerUrl ?? url : url) })
 		});
 	}
@@ -175,7 +200,7 @@ function pool(url) {
 		options: `-c search_path=${searchPath}`
 	});
 }
-
 //#endregion
 exports.KyselyDatabase = KyselyDatabase;
+
 //# sourceMappingURL=kysely.cjs.map