alchemy 0.1.18 → 0.2.0

package/lib/resource.d.ts

@@ -1,71 +1,43 @@
-import { type ApplyOptions } from "./apply";
-import type { DestroyOptions } from "./destroy";
-import type { Inputs, Input as input } from "./input";
-import { type Export, type Output, type Resolved } from "./output";
-import { type Scope as IScope } from "./scope";
-import type { State, StateStore } from "./state";
+import type { Context } from "./context";
+import { Scope as _Scope } from "./scope";
+export declare const PROVIDERS: Map<string, any>;
 export type ResourceID = string;
 export type ResourceFQN = string;
-export type ResourceType = string;
-export declare const ResourceID: unique symbol;
-export declare const ResourceFQN: unique symbol;
-export declare const ResourceHandle: unique symbol;
-export declare const Provider: unique symbol;
-export declare const Input: unique symbol;
-export declare const Value: unique symbol;
-export declare const Apply: unique symbol;
-export declare const Provide: unique symbol;
-export declare const Scope: unique symbol;
-export declare const Options: unique symbol;
+export type ResourceKind = string;
 export interface ProviderOptions {
     /**
      * If true, the resource will be updated even if the inputs have not changed.
      */
     alwaysUpdate: boolean;
 }
-export type Resource<In extends any[] = any[], Out = any> = {
-    [ResourceID]: string;
-    [Provider]: Provider<any, any[], any>;
-    [Input]: Inputs<In>;
-    [Value]?: Out;
-    [Apply]: <O>(value: Out) => O;
-    [Provide]: (value: Out) => void;
-    [Options]: ProviderOptions;
-} & Output<Out> & Export<Resolved<Out>>;
-export interface BaseContext {
-    quiet: boolean;
-    stage: string;
-    resourceID: ResourceID;
-    resourceFQN: ResourceFQN;
-    scope: IScope;
-    get<T>(key: string): Promise<T | undefined>;
-    set<T>(key: string, value: T): Promise<void>;
-    delete<T>(key: string): Promise<T | undefined>;
-    /**
-     * Indicate that this resource is being replaced.
-     * This will cause the resource to be deleted at the end of the stack's CREATE phase.
-     */
-    replace(): void;
-}
-export interface CreateContext extends BaseContext {
-    event: "create";
-    output?: undefined;
-}
-export interface UpdateContext<Outputs> extends BaseContext {
-    event: "update";
-    output: Outputs;
-}
-export interface DeleteContext<Outputs> extends BaseContext {
-    event: "delete";
-    output: Outputs;
-}
-export type Context<Outputs> = CreateContext | UpdateContext<Outputs> | DeleteContext<Outputs>;
-export type Provider<Type extends ResourceType = ResourceType, In extends any[] = any[], Out = any> = {
+export type ResourceProps = {
+    [key: string]: any;
+};
+export type Provider<Type extends string = string, F extends ResourceLifecycleHandler = ResourceLifecycleHandler> = F & IsClass & {
     type: Type;
-    update(stage: string, resource: Resource, deps: Set<ResourceID>, inputs: Inputs<In>, stateStore: StateStore, options: ApplyOptions): Promise<Awaited<Out>>;
-    delete(stage: string, scope: IScope | undefined, resourceID: ResourceID, state: State, inputs: Inputs<In>, options: DestroyOptions): Promise<void>;
-} & (new (id: string, ...inputs: [...Inputs<In>, ...any[]]) => Resource<In, Out>);
-export declare function isResource(value: any): value is Resource;
-export declare function Resource<Args extends any[], Out>(type: string, options: Partial<ProviderOptions>, func: (ctx: Context<Out>, ...args: Args) => Promise<input<Out> | void> | input<Out> | void): Provider<string, Args, Awaited<Out>>;
-export declare function Resource<const Type extends ResourceType, Args extends any[], Out>(type: Type, func: (ctx: Context<Out>, ...args: Args) => Promise<input<Out> | void> | input<Out> | void): Provider<Type, Args, Awaited<Out>>;
-//# sourceMappingURL=resource.d.ts.map
+    options: Partial<ProviderOptions> | undefined;
+    handler: F;
+};
+export type PendingResource<Out = unknown, Kind extends ResourceKind = ResourceKind, ID extends ResourceID = ResourceID, FQN extends ResourceFQN = ResourceFQN, Scope extends _Scope = _Scope, Seq extends number = number> = Promise<Out> & {
+    Kind: Kind;
+    ID: ID;
+    FQN: FQN;
+    Seq: Seq;
+    Scope: Scope;
+    signal: () => void;
+};
+export interface Resource<Kind extends ResourceKind = ResourceKind, ID extends ResourceID = ResourceID, FQN extends ResourceFQN = ResourceFQN, Scope extends _Scope = _Scope, Seq extends number = number> {
+    Kind: Kind;
+    ID: ID;
+    FQN: FQN;
+    Scope: Scope;
+    Seq: Seq;
+}
+type IsClass = {
+    new (_: never): never;
+};
+type ResourceLifecycleHandler = (this: Context<any>, id: string, props: any) => Promise<Resource<string>>;
+type Handler<F extends (...args: any[]) => any> = F | (((this: any, id: string, props: Parameters<F>[1]) => never) & IsClass);
+export declare function Resource<const Type extends string, F extends ResourceLifecycleHandler>(type: Type, fn: F): Handler<F>;
+export declare function Resource<const Type extends string, F extends ResourceLifecycleHandler>(type: Type, options: Partial<ProviderOptions>, fn: F): Handler<F>;
+export {};

package/lib/resource.js

@@ -1,276 +1,35 @@
-import { alchemize } from "./alchemize";
 import { apply } from "./apply";
-import { defaultStateStore, deletions, providers } from "./global";
-import { OutputChain } from "./output";
-import { getScope, pushScope } from "./scope";
-export const ResourceID = Symbol.for("ResourceID");
-export const ResourceFQN = Symbol.for("ResourceFQN");
-export const ResourceHandle = Symbol.for("ResourceHandle");
-export const Provider = Symbol.for("Provider");
-export const Input = Symbol.for("Input");
-export const Value = Symbol.for("Value");
-export const Apply = Symbol.for("Apply");
-export const Provide = Symbol.for("Provide");
-export const Scope = Symbol.for("Scope");
-export const Options = Symbol.for("Options");
-// properties that pierce through the Proxy
-const OrthogonalProperties = [
-    ResourceID,
-    ResourceFQN,
-    ResourceHandle,
-    Provider,
-    Input,
-    Value,
-    Apply,
-    Provide,
-    Scope,
-    Options,
-];
-export function isResource(value) {
-    return value?.[ResourceID] !== undefined;
-}
-const applied = new Map();
-const destroyed = new WeakMap();
-const i = 0;
+import { Scope as _Scope } from "./scope";
+export const PROVIDERS = new Map();
 export function Resource(type, ...args) {
-    if (providers.has(type)) {
+    if (PROVIDERS.has(type)) {
         throw new Error(`Resource ${type} already exists`);
     }
-    const [options, func] = args.length === 2 ? args : [undefined, args[0]];
-    class Resource {
-        static type = type;
-        constructor(id, ...input) {
-            const scope = getScope();
-            const node = {
-                provider: Resource,
-                resource: this,
-            };
-            if (scope.nodes.has(id)) {
-                // TODO(sam): do we want to throw?
-                // it's kind of awesome that you can re-create a resource and call apply
-                // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
-            }
-            scope.nodes.set(id, node);
-            // const resourceFQN = scope.getScopePath(id) + "/" + id;
-            this[ResourceID] = id;
-            this[ResourceHandle] = new Object();
-            // this[ResourceFQN] = resourceFQN;
-            // this[ResourceFQN] = i++;
-            this[Provider] = Resource;
-            this[Input] = input;
-            this[Value] = undefined;
-            this[Scope] = scope;
-            this[Provide] = (value) => {
-                this[Value] = value;
-            };
-            this[Options] = {
-                alwaysUpdate: options?.alwaysUpdate ?? false,
-            };
-            return new Proxy(this, {
-                // TODO(sam): this won't work for the sub-class (class Table extends Resource)
-                getPrototypeOf() {
-                    return Resource.prototype;
-                },
-                get(target, prop) {
-                    if (OrthogonalProperties.includes(prop)) {
-                        return target[prop];
-                    }
-                    else if (prop === "apply") {
-                        return target[Apply].bind(target);
-                    }
-                    else {
-                        return target[Apply]((value) => value[prop]);
-                    }
-                },
-            });
-        }
-        apply(fn) {
-            return this[Apply](fn);
-        }
-        [Apply](fn) {
-            return new OutputChain(this, fn);
-        }
-        box = undefined;
-        [Provide](value) {
-            if (this.box) {
-                throw new Error(`Output ${this[ResourceID]} already has a value`);
-            }
-            this.box = { value };
-            const subscribers = this.subscribers;
-            this.subscribers = [];
-            subscribers.forEach((fn) => fn(value));
+    const [options, handler] = args.length === 2 ? args : [undefined, args[0]];
+    const provider = ((resourceID, props) => {
+        const scope = _Scope.current;
+        if (scope.resources.has(resourceID)) {
+            // TODO(sam): do we want to throw?
+            // it's kind of awesome that you can re-create a resource and call apply
+            // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
         }
-        subscribers = [];
-        /**
-         * @internal
-         */
-        subscribe(fn) {
-            if (this.box) {
-                fn(this.box.value);
-            }
-            else {
-                this.subscribers.push(fn);
-            }
-        }
-        static async update(stage, resource, deps, inputs, stateStore, options) {
-            // const stack = resource[ResourceStack];
-            const resourceID = resource[ResourceID];
-            const resourceFQN = `${resource[Scope].getScopePath(stage)}/${resourceID}`;
-            const cacheKey = resource[ResourceHandle];
-            if (!applied.has(cacheKey)) {
-                let res, rej;
-                const promise = new Promise((resolve, reject) => {
-                    res = resolve;
-                    rej = reject;
-                });
-                applied.set(cacheKey, promise);
-                update().then(res).catch(rej);
-                return promise;
-            }
-            return await applied.get(cacheKey);
-            async function update() {
-                let resourceState = await stateStore.get(resourceID);
-                if (resourceState === undefined) {
-                    resourceState = {
-                        provider: type,
-                        status: "creating",
-                        data: {},
-                        output: undefined,
-                        deps: [...deps],
-                        inputs,
-                    };
-                    await stateStore.set(resourceID, resourceState);
-                }
-                // Skip update if inputs haven't changed and resource is in a stable state
-                if (resourceState.status === "created" ||
-                    resourceState.status === "updated") {
-                    if (JSON.stringify(resourceState.inputs) === JSON.stringify(inputs) &&
-                        !resource[Options].alwaysUpdate) {
-                        if (!options?.quiet) {
-                            console.log(`Skip:    ${resourceFQN} (no changes)`);
-                        }
-                        if (resourceState.output !== undefined) {
-                            resource[Provide](resourceState.output);
-                        }
-                        return resourceState.output;
-                    }
-                }
-                const event = resourceState.status === "creating" ? "create" : "update";
-                resourceState.status = event === "create" ? "creating" : "updating";
-                resourceState.oldInputs = resourceState.inputs;
-                resourceState.inputs = inputs;
-                if (!options?.quiet) {
-                    console.log(`${event === "create" ? "Create" : "Update"}:  ${resourceFQN}`);
-                }
-                await stateStore.set(resourceID, resourceState);
-                let isReplaced = false;
-                const quiet = options.quiet ?? false;
-                const evaluated = await pushScope(resource[Scope], resourceID, async () => {
-                    const result = await func({
-                        stage,
-                        resourceID,
-                        resourceFQN,
-                        event,
-                        scope: getScope(),
-                        output: resourceState.output,
-                        replace: () => {
-                            if (isReplaced) {
-                                console.warn(`Resource ${type} ${resourceFQN} is already marked as REPLACE`);
-                                return;
-                            }
-                            isReplaced = true;
-                            deletions.push({
-                                id: resourceID,
-                                data: {
-                                    ...resourceState.data,
-                                },
-                                inputs: inputs,
-                            });
-                        },
-                        get: (key) => resourceState.data[key],
-                        set: async (key, value) => {
-                            resourceState.data[key] = value;
-                            await stateStore.set(resourceID, resourceState);
-                        },
-                        delete: async (key) => {
-                            const value = resourceState.data[key];
-                            delete resourceState.data[key];
-                            await stateStore.set(resourceID, resourceState);
-                            return value;
-                        },
-                        quiet,
-                    }, ...inputs);
-                    if (result === undefined) {
-                        return undefined;
-                    }
-                    const evaluated = await apply(result, {
-                        stage,
-                        scope: getScope(),
-                        quiet,
-                    });
-                    return evaluated;
-                });
-                if (!options?.quiet) {
-                    console.log(`${event === "create" ? "Created" : "Updated"}: ${resourceFQN}`);
-                }
-                await stateStore.set(resourceID, {
-                    provider: type,
-                    data: resourceState.data,
-                    status: event === "create" ? "created" : "updated",
-                    output: evaluated,
-                    inputs,
-                    deps: [...deps],
-                });
-                if (evaluated !== undefined) {
-                    resource[Provide](evaluated);
-                }
-                return evaluated;
-            }
-        }
-        static async delete(stage, scope, resourceID, state, inputs, options) {
-            const { Scope } = await import("./scope");
-            const resourceFQN = `${scope.getScopePath(stage)}/${resourceID}`;
-            const nestedScope = new Scope(resourceID, scope);
-            await alchemize({
-                mode: "destroy",
-                stage,
-                scope: nestedScope,
-                // TODO(sam): should use the appropriate state store
-                stateStore: defaultStateStore,
-                quiet: options.quiet,
-            });
-            if (!options?.quiet) {
-                console.log(`Delete:  ${resourceFQN}`);
-            }
-            await func({
-                stage,
-                scope,
-                resourceID: resourceID,
-                resourceFQN: resourceFQN,
-                event: "delete",
-                output: state.output,
-                replace() {
-                    throw new Error("Cannot replace a resource that is being deleted");
-                },
-                get: (key) => {
-                    return state.data[key];
-                },
-                set: async (key, value) => {
-                    state.data[key] = value;
-                },
-                delete: async (key) => {
-                    const value = state.data[key];
-                    delete state.data[key];
-                    return value;
-                },
-                quiet: options.quiet ?? false,
-            }, ...inputs);
-            if (!options?.quiet) {
-                console.log(`Deleted: ${resourceFQN}`);
-            }
-        }
-    }
-    providers.set(type, Resource);
-    return Resource;
+        // get a sequence number (unique within the scope) for the resource
+        const seq = scope.seq();
+        const meta = {
+            Kind: type,
+            ID: resourceID,
+            FQN: scope.fqn(resourceID),
+            Seq: seq,
+            Scope: scope,
+        };
+        const promise = apply(meta, props, options);
+        const resource = Object.assign(promise, meta);
+        scope.resources.set(resourceID, resource);
+        return resource;
+    });
+    provider.type = type;
+    provider.handler = handler;
+    provider.options = options;
+    PROVIDERS.set(type, provider);
+    return provider;
 }
-//# sourceMappingURL=resource.js.map

package/lib/scope.d.ts

@@ -1,18 +1,39 @@
-import type { Output } from "./output";
-import type { Provider, Resource } from "./resource";
+import type { PendingResource, ResourceID } from "./resource";
+import { type StateStore, type StateStoreType } from "./state";
+export type ScopeOptions = {
+    appName?: string;
+    stage: string;
+    parent?: Scope;
+    scopeName?: string;
+    password?: string;
+    stateStore?: StateStoreType;
+    quiet?: boolean;
+};
 export declare class Scope {
+    static get(): Scope | undefined;
+    static get current(): Scope;
+    readonly resources: Map<string, PendingResource>;
+    readonly appName: string | undefined;
+    readonly stage: string;
     readonly scopeName: string | null;
     readonly parent: Scope | undefined;
-    readonly nodes: Map<string, {
-        provider: Provider<any, any[], any>;
-        resource: Resource<any, any>;
-    }>;
-    readonly callbacks: Output<void>[];
-    constructor(scopeName?: string | null, parent?: Scope | undefined);
-    getScopePath(root: string): string;
+    readonly password: string | undefined;
+    readonly state: StateStore;
+    readonly quiet: boolean;
+    constructor(options: ScopeOptions);
+    delete(resourceID: ResourceID): Promise<void>;
+    private _seq;
+    seq(): number;
+    get chain(): string[];
+    enter(): void;
+    init(): Promise<void>;
+    deinit(): Promise<void>;
+    fqn(resourceID: ResourceID): string;
+    finalize(): Promise<void>;
+    run<T>(fn: (scope: Scope) => Promise<T>): Promise<T>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Returns a string representation of the scope.
+     */
+    toString(): string;
 }
-export declare const rootScope: Scope;
-export declare function getScope(): Scope;
-export declare function withScope<T>(scope: Scope, fn: () => T | Promise<T>): Promise<T>;
-export declare function pushScope<T>(parent: Scope, scopeName: string, fn: () => T | Promise<T>): Promise<T>;
-//# sourceMappingURL=scope.d.ts.map

package/lib/scope.js

@@ -1,30 +1,85 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import path from "node:path";
+import { FileSystemStateStore, } from "./state";
 const scopeStorage = new AsyncLocalStorage();
 export class Scope {
+    static get() {
+        return scopeStorage.getStore();
+    }
+    static get current() {
+        const scope = Scope.get();
+        if (!scope) {
+            throw new Error("Not running within an Alchemy Scope");
+        }
+        return scope;
+    }
+    resources = new Map();
+    appName;
+    stage;
     scopeName;
     parent;
-    nodes = new Map();
-    callbacks = [];
-    constructor(scopeName = null, parent = undefined) {
-        this.scopeName = scopeName;
-        this.parent = parent;
-    }
-    getScopePath(root) {
-        // First, compute the parent's scope path
-        const parentPath = this.parent ? this.parent.getScopePath(root) : root;
-        // Then join the current scope name (if any) onto the parent's path
-        return this.scopeName ? path.join(parentPath, this.scopeName) : parentPath;
+    password;
+    state;
+    quiet;
+    constructor(options) {
+        this.appName = options.appName;
+        this.stage = options.stage;
+        this.scopeName = options.scopeName ?? null;
+        this.parent = options.parent ?? Scope.get();
+        this.quiet = options.quiet ?? this.parent?.quiet ?? false;
+        if (this.parent && !this.scopeName) {
+            throw new Error("Scope name is required when creating a child scope");
+        }
+        this.password = options.password;
+        this.state = new (options.stateStore ?? FileSystemStateStore)(this);
+    }
+    async delete(resourceID) {
+        await this.state.delete(resourceID);
+        this.resources.delete(resourceID);
+    }
+    _seq = 0;
+    seq() {
+        return this._seq++;
+    }
+    get chain() {
+        const thisScope = this.scopeName ? [this.scopeName] : [];
+        const app = this.appName ? [this.appName] : [];
+        if (this.parent) {
+            return [...this.parent.chain, ...thisScope];
+        }
+        else {
+            return [...app, this.stage, ...thisScope];
+        }
+    }
+    enter() {
+        scopeStorage.enterWith(this);
+    }
+    async init() {
+        await this.state.init?.();
+    }
+    async deinit() {
+        await this.state.deinit?.();
+    }
+    fqn(resourceID) {
+        return [...this.chain, resourceID].join("/");
+    }
+    async finalize() {
+        // TODO
+    }
+    async run(fn) {
+        return scopeStorage.run(this, () => fn(this));
+    }
+    [Symbol.asyncDispose]() {
+        return this.finalize();
+    }
+    /**
+     * Returns a string representation of the scope.
+     */
+    toString() {
+        return `Scope(
+  chain=${this.chain.join("/")},
+  resources=[${Array.from(this.resources.values())
+            .map((r) => r.ID)
+            .join(",\n  ")}]
+)`;
     }
 }
-export const rootScope = new Scope(null);
-export function getScope() {
-    return scopeStorage.getStore() ?? rootScope;
-}
-export function withScope(scope, fn) {
-    return scopeStorage.run(scope, async () => fn());
-}
-export function pushScope(parent, scopeName, fn) {
-    return scopeStorage.run(new Scope(scopeName, parent), async () => fn());
-}
-//# sourceMappingURL=scope.js.map

package/lib/secret.d.ts

@@ -1,12 +1,7 @@
-import type { Input } from "./input";
-import { type Output } from "./output";
-export declare function secret<S extends Input<string> | undefined>(unencrypted: S): S extends undefined ? never : S extends Output<string> ? Output<Secret> : Secret;
 export declare class Secret {
     readonly unencrypted: string;
     readonly type = "secret";
     constructor(unencrypted: string);
 }
-export declare function setSecretPassphrase(passphrase: string): void;
-export declare function getSecretPassphrase(): string;
-export declare function tryGetSecretPassphrase(): string | undefined;
-//# sourceMappingURL=secret.d.ts.map
+export declare function isSecret(binding: any): binding is Secret;
+export declare function secret<S extends string | undefined>(unencrypted: S): Secret;

package/lib/secret.js

@@ -1,12 +1,3 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { isOutput } from "./output";
-const passphraseContext = new AsyncLocalStorage();
-export function secret(unencrypted) {
-    if (unencrypted === undefined) {
-        throw new Error("Secret cannot be undefined");
-    }
-    return (isOutput(unencrypted) ? unencrypted.apply(secret) : new Secret(unencrypted));
-}
 export class Secret {
     unencrypted;
     type = "secret";
@@ -14,17 +5,13 @@ export class Secret {
         this.unencrypted = unencrypted;
     }
 }
-export function setSecretPassphrase(passphrase) {
-    passphraseContext.enterWith(passphrase);
+export function isSecret(binding) {
+    return (binding instanceof Secret ||
+        (typeof binding === "object" && binding.type === "secret_text"));
 }
-export function getSecretPassphrase() {
-    const passphrase = passphraseContext.getStore();
-    if (!passphrase) {
-        throw new Error("No passphrase set");
+export function secret(unencrypted) {
+    if (unencrypted === undefined) {
+        throw new Error("Secret cannot be undefined");
     }
-    return passphrase;
-}
-export function tryGetSecretPassphrase() {
-    return passphraseContext.getStore();
+    return new Secret(unencrypted);
 }
-//# sourceMappingURL=secret.js.map

package/lib/state.d.ts

@@ -1,12 +1,17 @@
-export interface State {
+import type { Resource, ResourceProps } from "./resource";
+import type { Scope } from "./scope";
+export interface State<Kind extends string = string, Props extends ResourceProps = ResourceProps, Out extends Resource = Resource> {
     status: `creating` | `created` | `updating` | `updated` | `deleting` | `deleted`;
-    provider: string;
+    kind: Kind;
+    id: string;
+    fqn: string;
+    seq: number;
     data: Record<string, any>;
-    deps: string[];
-    inputs: any[];
-    oldInputs?: any[];
-    output: any;
+    props: Props;
+    oldProps?: Props;
+    output: Out;
 }
+export type StateStoreType = new (scope: Scope) => StateStore;
 export interface StateStore {
     /** Initialize the state container if one is required */
     init?(): Promise<void>;
@@ -22,10 +27,10 @@ export interface StateStore {
     set(key: string, value: State): Promise<void>;
     delete(key: string): Promise<void>;
 }
-export type StateStoreType = new (dir: string) => StateStore;
 export declare class FileSystemStateStore implements StateStore {
-    readonly path: string;
-    constructor(dir: string);
+    readonly scope: Scope;
+    readonly dir: string;
+    constructor(scope: Scope);
     init(): Promise<void>;
     deinit(): Promise<void>;
     count(): Promise<number>;
@@ -37,4 +42,3 @@ export declare class FileSystemStateStore implements StateStore {
     getBatch(ids: string[]): Promise<Record<string, State>>;
     private getPath;
 }
-//# sourceMappingURL=state.d.ts.map