@justscale/core 0.1.0

package/dist/features/lock/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Lock Type Definitions
+ *
+ * Generic lock types that can wrap any object.
+ * The constraint that locks only apply to Persistent entities
+ * is enforced at the usage site (e.g., in Repository).
+ */
+declare const LockBrand: unique symbol;
+/**
+ * Make all fields mutable.
+ * Used by Lock<T> to allow modification of domain data.
+ */
+type MakeMutable<T> = {
+    -readonly [K in keyof T]: T[K];
+};
+/**
+ * Metadata attached to a locked object.
+ */
+export interface LockMetadata {
+    readonly lockedAt: Date;
+    readonly expiresAt: Date;
+    readonly lockedBy: string;
+}
+/**
+ * Marks an object as locked (exclusive access acquired).
+ *
+ * - Type-branded so functions can require lock proof as a parameter
+ * - Implements `Disposable` (sync, fire-and-forget release) AND
+ *   `AsyncDisposable` (preferred — `await using` awaits release ordering)
+ * - `__active` flips to `false` after dispose. Mutators (`update`,
+ *   `delete`, `save` on Repository) reject inactive locks with
+ *   `LockReleasedError` to catch the use-after-dispose foot-gun.
+ *
+ * @example
+ * ```typescript
+ * // Preferred: await using — awaits the release before next code runs
+ * await using user = await lockService.acquire(userRepo.get(User.ref(id)));
+ *
+ * // Pass to service that requires lock proof
+ * await paymentService.processRefund(user);
+ *
+ * // Lock awaited-released when scope exits
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Service requiring lock proof - prevents deadlocks from nested acquisition
+ * class PaymentService {
+ *   async processRefund(user: Lock<Persistent<User>>) {
+ *     // Type proves caller owns the lock - no nested locking needed
+ *     user.balance += refundAmount;
+ *     await this.userRepo.save(user);
+ *   }
+ * }
+ * ```
+ */
+export type Lock<T> = MakeMutable<T> & {
+    readonly [LockBrand]: true;
+    readonly __lock: LockMetadata;
+    /**
+     * True while the lock is held. Flips to false on `Symbol.dispose`
+     * or `Symbol.asyncDispose`. Mutator APIs (`Repository.update` etc.)
+     * check this and throw `LockReleasedError` if false.
+     */
+    readonly __active: boolean;
+} & Disposable & AsyncDisposable;
+/**
+ * Helper to check if an object is locked at runtime.
+ */
+export declare function isLocked<T>(obj: unknown): obj is Lock<T>;
+/**
+ * Options for acquiring a lock.
+ */
+export interface LockOptions {
+    /** Time-to-live in milliseconds. Lock auto-expires after this. Default: 30000 (30s) */
+    ttl?: number;
+    /** How long to wait for lock acquisition before failing. Default: 5000 (5s) */
+    timeout?: number;
+    /** Custom lock key. Default: derived from object */
+    key?: string;
+    /** Enable heartbeat to auto-extend lock. Default: false. Provider support varies. */
+    heartbeat?: boolean;
+    /** Heartbeat interval in ms. Default: ttl/3. Only used if heartbeat is enabled. */
+    heartbeatInterval?: number;
+}
+/**
+ * Lock storage backend interface.
+ *
+ * Implementations: InMemoryLockProvider, PostgresLockProvider, RedisLockProvider
+ *
+ * JustScale locks are ALWAYS blocking - acquire() waits forever until the lock
+ * is obtained. There is no timeout, no failure. Each backend implements its own
+ * efficient waiting mechanism (pub/sub, LISTEN/NOTIFY, waiter sets, etc.).
+ */
+export interface LockProvider {
+    /**
+     * Acquire a lock, blocking until acquired.
+     *
+     * IMPORTANT: This method blocks forever until the lock is obtained.
+     * There is no timeout. Implementations must notify waiters on release.
+     *
+     * @returns Lock metadata once acquired
+     */
+    acquire(key: string, options: Required<LockOptions>, instanceId: string): Promise<LockMetadata>;
+    /**
+     * Release a lock and notify any waiters.
+     *
+     * Safe to call even if the lock is not held or owned by another instance.
+     * Must notify any waiting acquire() calls that the lock is available.
+     */
+    release(key: string, instanceId: string): Promise<void>;
+    /**
+     * Extend a lock's TTL. Used for long-running operations.
+     *
+     * @returns true if extended, false if lock not held or owned by another
+     */
+    extend(key: string, instanceId: string, ttl: number): Promise<boolean>;
+    /**
+     * Close the lock provider, releasing all held locks.
+     * Should be called on graceful shutdown.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Service for acquiring distributed locks.
+ *
+ * Generic interface - concrete implementations may add constraints
+ * (e.g., only allowing Persistent entities).
+ */
+export interface LockService<T = unknown> {
+    /**
+     * Acquire an exclusive lock on an object.
+     *
+     * - If passed a direct object, locks it and returns Lock<T>
+     * - If passed a Promise, awaits it then locks
+     * - If the object is null, returns null (no lock acquired)
+     *
+     * @example
+     * ```typescript
+     * // Direct object
+     * using user = await lockService.acquire(existingUser);
+     *
+     * // From Promise (chain with repo call)
+     * using user = await lockService.acquire(userRepo.get(User.ref(id)));
+     * if (!user) throw new NotFoundError();
+     * ```
+     */
+    acquire(obj: T | Promise<T> | null | Promise<T | null>, options?: LockOptions): Promise<Lock<T> | null>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/features/lock/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/lock/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,CAAC,MAAM,SAAS,EAAE,OAAO,MAAM,CAAC;AAEvC;;;GAGG;AACH,KAAK,WAAW,CAAC,CAAC,IAAI;IACpB,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IACrC,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B,GAAG,UAAU,GAAG,eAAe,CAAC;AAEjC;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAOxD;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,OAAO,CACL,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC9B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvE;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CACL,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC9C,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAC5B"}

package/dist/features/lock/types.js

@@ -0,0 +1,17 @@
+/**
+ * Lock Type Definitions
+ *
+ * Generic lock types that can wrap any object.
+ * The constraint that locks only apply to Persistent entities
+ * is enforced at the usage site (e.g., in Repository).
+ */
+/**
+ * Helper to check if an object is locked at runtime.
+ */
+export function isLocked(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        '__lock' in obj &&
+        Symbol.dispose in obj);
+}
+//# sourceMappingURL=types.js.map

package/dist/features/lock/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/lock/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiEH;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAY;IACtC,OAAO,CACL,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,QAAQ,IAAI,GAAG;QACf,MAAM,CAAC,OAAO,IAAI,GAAG,CACtB,CAAC;AACJ,CAAC"}

package/dist/features/memory/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * In-Memory Adapters
+ *
+ * Simple in-memory implementations for development and testing.
+ * These are not suitable for production multi-node deployments.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryLockFeature } from '@justscale/core/memory'
+ *
+ * JustScale()
+ *   .add(InMemoryLockFeature)
+ *   .build()
+ * ```
+ */
+export { InMemoryLockProvider, createInMemoryLockProvider, type InMemoryLockProviderInstance, } from '../lock/memory.js';
+export { InMemoryLockFeature } from './lock-feature.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/features/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,KAAK,4BAA4B,GAClC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/features/memory/index.js

@@ -0,0 +1,18 @@
+/**
+ * In-Memory Adapters
+ *
+ * Simple in-memory implementations for development and testing.
+ * These are not suitable for production multi-node deployments.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryLockFeature } from '@justscale/core/memory'
+ *
+ * JustScale()
+ *   .add(InMemoryLockFeature)
+ *   .build()
+ * ```
+ */
+export { InMemoryLockProvider, createInMemoryLockProvider, } from '../lock/memory.js';
+export { InMemoryLockFeature } from './lock-feature.js';
+//# sourceMappingURL=index.js.map

package/dist/features/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/features/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,oBAAoB,EACpB,0BAA0B,GAE3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/features/memory/lock-feature.d.ts

@@ -0,0 +1,21 @@
+/**
+ * In-Memory Lock Feature
+ *
+ * Provides in-memory locking for single-node apps, development, and testing.
+ * For distributed locking across multiple instances, use PostgresLockFeature.
+ *
+ * @example
+ * ```typescript
+ * import JustScale from '@justscale/core'
+ * import { InMemoryLockFeature } from '@justscale/core/memory'
+ * import { InMemoryProcessFeature } from '@justscale/core/process'
+ *
+ * JustScale()
+ *   .add(InMemoryLockFeature)
+ *   .add(InMemoryProcessFeature)
+ *   .build()
+ * ```
+ */
+import { InMemoryLockProvider } from '../lock/memory.js';
+export declare const InMemoryLockFeature: import("../../builder/types.js").FeatureToken<[], [typeof InMemoryLockProvider]>;
+//# sourceMappingURL=lock-feature.d.ts.map

package/dist/features/memory/lock-feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-feature.d.ts","sourceRoot":"","sources":["../../../src/features/memory/lock-feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,eAAO,MAAM,mBAAmB,kFAI7B,CAAC"}

package/dist/features/memory/lock-feature.js

@@ -0,0 +1,24 @@
+/**
+ * In-Memory Lock Feature
+ *
+ * Provides in-memory locking for single-node apps, development, and testing.
+ * For distributed locking across multiple instances, use PostgresLockFeature.
+ *
+ * @example
+ * ```typescript
+ * import JustScale from '@justscale/core'
+ * import { InMemoryLockFeature } from '@justscale/core/memory'
+ * import { InMemoryProcessFeature } from '@justscale/core/process'
+ *
+ * JustScale()
+ *   .add(InMemoryLockFeature)
+ *   .add(InMemoryProcessFeature)
+ *   .build()
+ * ```
+ */
+import { createFeatureBuilder } from '../../builder/index.js';
+import { InMemoryLockProvider } from '../lock/memory.js';
+export const InMemoryLockFeature = createFeatureBuilder()
+    .name('InMemoryLock')
+    .provides((b) => b.add(InMemoryLockProvider));
+//# sourceMappingURL=lock-feature.js.map

package/dist/features/memory/lock-feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-feature.js","sourceRoot":"","sources":["../../../src/features/memory/lock-feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,EAAE;KACtD,IAAI,CAAC,cAAc,CAAC;KACpB,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CACd,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAC5B,CAAC"}

package/dist/features/secrets/create-secret-provider.d.ts

@@ -0,0 +1,31 @@
+import type { ServiceToken, InstanceOf } from '../../core/service.js';
+import type { SecretPartial, SecretComponent } from './types.js';
+type InferDeps<T extends Record<string, ServiceToken<any>>> = {
+    [K in keyof T]: InstanceOf<T[K]>;
+};
+type SecretFactory<TInject extends Record<string, ServiceToken<any>>> = (deps: InferDeps<TInject>) => Record<symbol, any> | Promise<Record<symbol, any>>;
+interface CreateSecretProviderOptions<TInject extends Record<string, ServiceToken<any>>, P extends readonly SecretPartial<any>[]> {
+    provides?: P;
+    inject?: TInject;
+    factory: SecretFactory<TInject>;
+}
+/**
+ * Create a SecretProvider - a component that loads secrets from a source
+ * (vault client, hardcoded values, process.env) at boot.
+ *
+ * The factory returns `{ [partial.key]: value }`. When `provides` is set,
+ * each value is validated against its partial's zod schema.
+ *
+ * @example
+ * const ProdSecrets = createSecretProvider({
+ *   provides: [PostgresSecrets, JwtSecrets],
+ *   inject: { vault: KubernetesVaultClient },
+ *   factory: async ({ vault }) => ({
+ *     [PostgresSecrets.key]: { connectionString: await vault.read('postgres/url') },
+ *     [JwtSecrets.key]: { signingKey: await vault.read('jwt/key') },
+ *   }),
+ * })
+ */
+export declare function createSecretProvider<const TInject extends Record<string, ServiceToken<any>> = {}, const P extends readonly SecretPartial<any>[] = readonly []>(options: CreateSecretProviderOptions<TInject, P>): SecretComponent<P>;
+export {};
+//# sourceMappingURL=create-secret-provider.d.ts.map

package/dist/features/secrets/create-secret-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-secret-provider.d.ts","sourceRoot":"","sources":["../../../src/features/secrets/create-secret-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI;KAC3D,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,IAClE,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAEnF,UAAU,2BAA2B,CACnC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,EACjD,CAAC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE;IAEvC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAC5D,KAAK,CAAC,CAAC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,EAAE,EAC3D,OAAO,EAAE,2BAA2B,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAOtE"}

package/dist/features/secrets/create-secret-provider.js

@@ -0,0 +1,26 @@
+/**
+ * Create a SecretProvider - a component that loads secrets from a source
+ * (vault client, hardcoded values, process.env) at boot.
+ *
+ * The factory returns `{ [partial.key]: value }`. When `provides` is set,
+ * each value is validated against its partial's zod schema.
+ *
+ * @example
+ * const ProdSecrets = createSecretProvider({
+ *   provides: [PostgresSecrets, JwtSecrets],
+ *   inject: { vault: KubernetesVaultClient },
+ *   factory: async ({ vault }) => ({
+ *     [PostgresSecrets.key]: { connectionString: await vault.read('postgres/url') },
+ *     [JwtSecrets.key]: { signingKey: await vault.read('jwt/key') },
+ *   }),
+ * })
+ */
+export function createSecretProvider(options) {
+    return {
+        __secretComponent: true,
+        provides: (options.provides ?? []),
+        inject: (options.inject ?? {}),
+        factory: options.factory,
+    };
+}
+//# sourceMappingURL=create-secret-provider.js.map

package/dist/features/secrets/create-secret-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-secret-provider.js","sourceRoot":"","sources":["../../../src/features/secrets/create-secret-provider.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAGlC,OAAgD;IAChD,OAAO;QACL,iBAAiB,EAAE,IAAI;QACvB,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAM;QACvC,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAA+B;QAC5D,OAAO,EAAE,OAAO,CAAC,OAA2D;KAC7E,CAAC;AACJ,CAAC"}

package/dist/features/secrets/define-secret-partial.d.ts

@@ -0,0 +1,16 @@
+import type { z } from 'zod';
+import { type SecretPartial } from './types.js';
+/**
+ * Define a secret partial with a Zod schema.
+ *
+ * Secret partials describe the shape of a secret slice (e.g. Postgres
+ * connection string, JWT signing key). The value is provided at boot by a
+ * SecretProvider that reads from a vault.
+ *
+ * @example
+ * const PostgresSecrets = defineSecretPartial('postgres', z.object({
+ *   connectionString: z.string(),
+ * }))
+ */
+export declare function defineSecretPartial<T extends z.ZodType>(name: string, schema: T): SecretPartial<z.infer<T>>;
+//# sourceMappingURL=define-secret-partial.d.ts.map

package/dist/features/secrets/define-secret-partial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-secret-partial.d.ts","sourceRoot":"","sources":["../../../src/features/secrets/define-secret-partial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EACrD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,GACR,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAW3B"}

package/dist/features/secrets/define-secret-partial.js

@@ -0,0 +1,26 @@
+import { SECRET_PARTIAL } from './types.js';
+/**
+ * Define a secret partial with a Zod schema.
+ *
+ * Secret partials describe the shape of a secret slice (e.g. Postgres
+ * connection string, JWT signing key). The value is provided at boot by a
+ * SecretProvider that reads from a vault.
+ *
+ * @example
+ * const PostgresSecrets = defineSecretPartial('postgres', z.object({
+ *   connectionString: z.string(),
+ * }))
+ */
+export function defineSecretPartial(name, schema) {
+    return {
+        [SECRET_PARTIAL]: true,
+        // Plain Symbol(): each defineSecretPartial() call produces a fresh
+        // token even when two features reuse the same human-readable name.
+        // Consumers import the partial object from its declaring module and
+        // inject it directly, so no global string-keyed lookup exists.
+        key: Symbol(`secret:${name}`),
+        name,
+        schema: schema,
+    };
+}
+//# sourceMappingURL=define-secret-partial.js.map

package/dist/features/secrets/define-secret-partial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-secret-partial.js","sourceRoot":"","sources":["../../../src/features/secrets/define-secret-partial.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,MAAS;IAET,OAAO;QACL,CAAC,cAAc,CAAC,EAAE,IAAI;QACtB,mEAAmE;QACnE,mEAAmE;QACnE,oEAAoE;QACpE,+DAA+D;QAC/D,GAAG,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;QAC7B,IAAI;QACJ,MAAM,EAAE,MAA+B;KACxC,CAAC;AACJ,CAAC"}

package/dist/features/secrets/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @justscale/core/secrets
+ *
+ * Read-only, vault-backed secret management.
+ *
+ * Mirrors the config partial pattern but reserved for secrets - no runtime
+ * mutation, no disk persistence, values loaded once at boot from a vault.
+ */
+export { SECRET_PARTIAL, isSecretPartial, isSecretComponent, } from './types.js';
+export type { SecretPartial, SecretComponent, } from './types.js';
+export { defineSecretPartial } from './define-secret-partial.js';
+export { Secret } from './secret-of.js';
+export type { SecretToken } from './secret-of.js';
+export { createSecretProvider } from './create-secret-provider.js';
+export { SecretServiceDef } from './secret-service.js';
+export type { SecretService } from './secret-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/features/secrets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/secrets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/features/secrets/index.js

@@ -0,0 +1,14 @@
+/**
+ * @justscale/core/secrets
+ *
+ * Read-only, vault-backed secret management.
+ *
+ * Mirrors the config partial pattern but reserved for secrets - no runtime
+ * mutation, no disk persistence, values loaded once at boot from a vault.
+ */
+export { SECRET_PARTIAL, isSecretPartial, isSecretComponent, } from './types.js';
+export { defineSecretPartial } from './define-secret-partial.js';
+export { Secret } from './secret-of.js';
+export { createSecretProvider } from './create-secret-provider.js';
+export { SecretServiceDef } from './secret-service.js';
+//# sourceMappingURL=index.js.map

package/dist/features/secrets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/features/secrets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/features/secrets/secret-of.d.ts

@@ -0,0 +1,19 @@
+import type { Token } from '../../builder/index.js';
+import type { SecretPartial } from './types.js';
+declare const SECRET_TOKEN_BRAND: unique symbol;
+/**
+ * A secret token for DI. Services inject via Secret.of(partial).
+ */
+export interface SecretToken<T> extends Token<T> {
+    readonly [SECRET_TOKEN_BRAND]?: T;
+    readonly description: string;
+    readonly key: symbol;
+    resolve(container: {
+        get(key: symbol): T;
+    }): T;
+}
+export declare const Secret: {
+    of<T>(partial: SecretPartial<T>): SecretToken<T>;
+};
+export {};
+//# sourceMappingURL=secret-of.d.ts.map

package/dist/features/secrets/secret-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-of.d.ts","sourceRoot":"","sources":["../../../src/features/secrets/secret-of.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,CAAC,MAAM,kBAAkB,EAAE,OAAO,MAAM,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IAC9C,QAAQ,CAAC,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,SAAS,EAAE;QAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAA;KAAE,GAAG,CAAC,CAAA;CAC/C;AASD,eAAO,MAAM,MAAM;OACd,CAAC,WAAW,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;CAWjD,CAAC"}

package/dist/features/secrets/secret-of.js

@@ -0,0 +1,21 @@
+/**
+ * Memoize per-partial to preserve token identity across call-sites -
+ * required so DI validation matches the token a service injects against
+ * the token a SecretProvider declares in `provides`.
+ */
+const secretTokenCache = new WeakMap();
+export const Secret = {
+    of(partial) {
+        const cached = secretTokenCache.get(partial);
+        if (cached)
+            return cached;
+        const token = {
+            description: `Secret.of(${partial.name})`,
+            key: partial.key,
+            resolve: (container) => container.get(partial.key),
+        };
+        secretTokenCache.set(partial, token);
+        return token;
+    },
+};
+//# sourceMappingURL=secret-of.js.map

package/dist/features/secrets/secret-of.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-of.js","sourceRoot":"","sources":["../../../src/features/secrets/secret-of.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAwC,CAAC;AAE7E,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,CAAI,OAAyB;QAC7B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,MAAM;YAAE,OAAO,MAAwB,CAAC;QAC5C,MAAM,KAAK,GAAmB;YAC5B,WAAW,EAAE,aAAa,OAAO,CAAC,IAAI,GAAG;YACzC,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,CAAC,SAAsC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC;SAC9D,CAAC;QACpB,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC"}

package/dist/features/secrets/secret-service.d.ts

@@ -0,0 +1,21 @@
+import type { SecretPartial } from './types.js';
+/**
+ * Read-only secret access service.
+ *
+ * Intentionally has NO .set(), no persistence to disk, no watch. Secrets are
+ * loaded at boot by SecretProviders and are immutable for the process
+ * lifetime. Rotation = restart the process (k8s rolling deploy).
+ */
+export interface SecretService {
+    /**
+     * Read the current value for a secret partial.
+     *
+     * @throws if no provider has registered a value for this partial
+     */
+    read<T>(partial: SecretPartial<T>): Promise<T>;
+}
+declare const SecretServiceDef_base: import("../../core/service.js").Service<SecretService, {}>;
+export declare class SecretServiceDef extends SecretServiceDef_base {
+}
+export {};
+//# sourceMappingURL=secret-service.d.ts.map

package/dist/features/secrets/secret-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-service.d.ts","sourceRoot":"","sources":["../../../src/features/secrets/secret-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAC/C;;AAuBD,qBAAa,gBAAiB,SAAQ,qBAGpC;CAAG"}

package/dist/features/secrets/secret-service.js

@@ -0,0 +1,28 @@
+import { defineService } from '../../core/index.js';
+import { Secret } from './secret-of.js';
+class SecretServiceImpl {
+    resolver;
+    constructor(resolver) {
+        this.resolver = resolver;
+    }
+    async read(partial) {
+        // Route through the partial's ResolvableToken (Secret.of) instead of the
+        // raw symbol. The container's resolvable-token branch looks the value
+        // up via container.instances.get(partial.key) and returns undefined
+        // when nothing is registered; we surface the friendly error below.
+        // Passing the raw symbol used to reach resolveInternal's
+        // `'deps' in token` check and threw an opaque TypeError.
+        const value = await this.resolver(Secret.of(partial));
+        if (value === undefined) {
+            throw new Error(`SecretService.read: no provider registered a value for secret partial '${partial.name}'. ` +
+                `Did you add a createSecretProvider() that returns { [${partial.name}.key]: ... }?`);
+        }
+        return value;
+    }
+}
+export class SecretServiceDef extends defineService({
+    inject: {},
+    factory: (_deps, resolver) => new SecretServiceImpl(resolver),
+}) {
+}
+//# sourceMappingURL=secret-service.js.map

package/dist/features/secrets/secret-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-service.js","sourceRoot":"","sources":["../../../src/features/secrets/secret-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAmBxC,MAAM,iBAAiB;IACQ;IAA7B,YAA6B,QAAkB;QAAlB,aAAQ,GAAR,QAAQ,CAAU;IAAG,CAAC;IAEnD,KAAK,CAAC,IAAI,CAAI,OAAyB;QACrC,yEAAyE;QACzE,sEAAsE;QACtE,oEAAoE;QACpE,mEAAmE;QACnE,yDAAyD;QACzD,yDAAyD;QACzD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAI,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,0EAA0E,OAAO,CAAC,IAAI,KAAK;gBAC3F,wDAAwD,OAAO,CAAC,IAAI,eAAe,CACpF,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,aAAa,CAAC;IAClD,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAiB,EAAE,CAAC,IAAI,iBAAiB,CAAC,QAAQ,CAAC;CAC7E,CAAC;CAAG"}

package/dist/features/secrets/types.d.ts

@@ -0,0 +1,30 @@
+import type { z } from 'zod';
+import type { Token } from '../../builder/index.js';
+export declare const SECRET_PARTIAL: unique symbol;
+/**
+ * A secret partial - defines shape and validation for a secret slice.
+ *
+ * Parallel to ConfigPartial but reserved for secrets. Secrets are NEVER
+ * mutated at runtime (no .set, no persistence to .justscale/). Values come
+ * from a vault-backed SecretProvider at boot and are read-only thereafter.
+ */
+export interface SecretPartial<T> {
+    readonly [SECRET_PARTIAL]: true;
+    readonly key: symbol;
+    readonly name: string;
+    readonly schema: z.ZodType<T>;
+}
+export declare function isSecretPartial(value: unknown): value is SecretPartial<unknown>;
+/**
+ * Component returned by createSecretProvider().
+ * Builder runs its factory at boot, validates each returned value against
+ * its partial's schema, and registers the results under partial keys.
+ */
+export interface SecretComponent<P extends readonly SecretPartial<any>[] = readonly SecretPartial<any>[]> {
+    readonly __secretComponent: true;
+    readonly provides: P;
+    readonly inject: Record<string, Token<any>>;
+    readonly factory: (deps: Record<string, any>) => Record<symbol, any> | Promise<Record<symbol, any>>;
+}
+export declare function isSecretComponent(value: unknown): value is SecretComponent;
+//# sourceMappingURL=types.d.ts.map

package/dist/features/secrets/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/secrets/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CAC9B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAE/E;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE;IACtG,QAAQ,CAAC,iBAAiB,EAAE,IAAI,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;CACpG;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}

package/dist/features/secrets/types.js

@@ -0,0 +1,8 @@
+export const SECRET_PARTIAL = Symbol('secret:partial');
+export function isSecretPartial(value) {
+    return typeof value === 'object' && value !== null && SECRET_PARTIAL in value;
+}
+export function isSecretComponent(value) {
+    return typeof value === 'object' && value !== null && '__secretComponent' in value;
+}
+//# sourceMappingURL=types.js.map

package/dist/features/secrets/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/secrets/types.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAgBvD,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,cAAc,IAAI,KAAK,CAAC;AAChF,CAAC;AAcD,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,mBAAmB,IAAI,KAAK,CAAC;AACrF,CAAC"}

package/dist/features/vault/env-var-vault.d.ts

@@ -0,0 +1,24 @@
+import { type VaultClient } from './types.js';
+declare const EnvVarVault_base: import("../../core/service.js").Service<VaultClient, {}>;
+/**
+ * EnvVarVault - reads raw values from `process.env`.
+ *
+ * The path is transformed to an uppercase env-var name: `/` and `-` become
+ * `_`. E.g. `read('postgres/url')` reads `POSTGRES_URL`.
+ *
+ * Apps use it uniformly for both secrets (via `postgresSecret(...)`) and
+ * non-secret config overrides (via `fromVault(partial, {...})`), so the
+ * production composition never reads `process.env` directly.
+ *
+ * @example
+ * export default createEnvironment({
+ *   name: 'production',
+ *   type: 'production',
+ *   services: [EnvVarVault],
+ *   providers: [...],
+ * })
+ */
+export declare class EnvVarVault extends EnvVarVault_base {
+}
+export {};
+//# sourceMappingURL=env-var-vault.d.ts.map

package/dist/features/vault/env-var-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-var-vault.d.ts","sourceRoot":"","sources":["../../../src/features/vault/env-var-vault.ts"],"names":[],"mappings":"AACA,OAAO,EAAmC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAY,SAAQ,gBAkB/B;CAAG"}