@marko/ts-plugin 0.0.0 → 3.1.0

package/dist/marko.runtime.d.ts

@@ -0,0 +1,410 @@
+import "./tags-html";
+
+declare module "*.marko" {
+  const template: Marko.Template;
+  export default template;
+}
+
+declare global {
+  namespace NodeJS {
+    interface ReadableStream {}
+  }
+
+  namespace Marko {
+    /** A mutable global object for the current render. */
+    export interface Global {
+      [x: PropertyKey]: unknown;
+      /** An AbortSignal instance that, when aborted, stops further streamed content. */
+      signal?: AbortSignal;
+      /** A CSP Nonce to add to each script output from Marko. */
+      cspNonce?: string;
+      /** Used for rendering multiple Marko templates in a single hydrated page. */
+      renderId?: string;
+      /** Used to uniquely identify a instance of a Marko runtime. */
+      runtimeId?: string;
+      /** A list of globals that should be serialized to the browser. */
+      serializedGlobals?: Record<string, boolean>;
+      /** @deprecated prefer `renderId` */
+      widgetIdPrefix?: string;
+      /** @deprecated prefer `renderId` */
+      componentIdPrefix?: string;
+    }
+
+    export type TemplateInput<Input> = Input & {
+      $global?: Global;
+    };
+
+    /** The result of calling `template.render`. */
+    export type RenderedTemplate<Component = unknown> = Promise<
+      Component extends Marko.Component ? RenderResult<Component> : string
+    > &
+      AsyncIterable<string> & {
+        toReadable(): ReadableStream<Uint8Array<ArrayBufferLike>>;
+        pipe(stream: {
+          write(chunk: string): unknown;
+          end(): unknown;
+          flush?(): void;
+        }): void;
+        toString(): string;
+      };
+
+    /** The result of calling `template.mount`. */
+    export type MountedTemplate<Input = unknown, Return = unknown> = {
+      get value(): Return extends { value: infer Value } ? Value : void;
+      set value(
+        next: Return extends { valueChange?(next: infer Next): any }
+          ? Next
+          : never,
+      );
+      update(input: Marko.TemplateInput<Input>): void;
+      destroy(): void;
+    };
+
+    export interface Out<
+      Component = unknown,
+    > extends Marko.RenderedTemplate<Component> {
+      /** The underlying ReadableStream Marko is writing into. */
+      stream: unknown;
+      /** A mutable global object for the current render. */
+      global: Global;
+      /** Disable all async rendering. Will error if something beings async. */
+      sync(): void;
+      /** Returns true if async rendering is disabled. */
+      isSync(): boolean;
+      /** Write unescaped text at the current stream position. */
+      write(val: string | void): this;
+      /** Write javascript content to be merged with the scripts Marko sends out on the next flush. */
+      script(val: string | void): this;
+      /** Starts a new async/forked stream. */
+      beginAsync(options?: {
+        name?: string;
+        timeout?: number;
+        last?: boolean;
+      }): Out;
+      /** Marks the current stream as complete (async streams may still be executing). */
+      end(val?: string | void): this;
+      emit(eventName: PropertyKey, ...args: any[]): boolean;
+      on(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+      once(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+      prependListener(
+        eventName: PropertyKey,
+        listener: (...args: any[]) => any,
+      ): this;
+      removeListener(
+        eventName: PropertyKey,
+        listener: (...args: any[]) => any,
+      ): this;
+      /** Register a callback executed when the last async out has completed. */
+      onLast(listener: (next: () => void) => unknown): this;
+      /** Emits an error on the stream. */
+      error(e: Error): this;
+      /** Schedules a Marko to flush buffered html to the underlying stream. */
+      flush(): this;
+      /** Creates a detached out stream (used for out of order flushing). */
+      createOut(): Out;
+      /** Write escaped text at the current stream position. */
+      text(val: string | void): void;
+    }
+
+    /** Body content created from by a component, typically held in an object with a renderBody property. */
+
+    export interface Body<
+      in Params extends readonly any[] = [],
+      out Return = void,
+    > {}
+
+    /** Valid data types which can be passed in as a <${dynamic}/> tag name. */
+    export type Renderable =
+      | { renderBody: Body<any, any> | Template | string }
+      | Body<any, any>
+      | Template
+      | string;
+
+    /** Extract the return tag type from a renderBody. */
+    export type BodyReturnType<B> =
+      B extends Body<any, infer Return> ? Return : never;
+
+    /** Extract the tag parameter types received by a renderBody. */
+    export type BodyParameters<B> =
+      B extends Body<infer Params, any> ? Params : never;
+
+    export class Component<
+      Input = unknown,
+      State = unknown,
+    > implements Emitter {
+      /** A unique id for this instance. */
+      public readonly id: string;
+      /** The top level element rendered by this instance. */
+      public readonly el: Element | void;
+      /** The attributes passed to this instance. */
+      public readonly input: Input;
+      /** @deprecated */
+      public readonly els: Element[];
+      /** Mutable state that when changed causes a rerender. */
+      state: State;
+
+      /** Returns the amount of event handlers listening to a specific event. */
+      listenerCount(eventName: PropertyKey): number;
+      /**
+       * Used to wrap an existing event emitted and ensure that all events are
+       * cleaned up once this component is destroyed
+       * */
+      subscribeTo(
+        emitter: unknown,
+      ): Omit<Emitter, "listenerCount" | "prependListener" | "emit">;
+      /** Emits an event on the component instance. */
+      emit(eventName: PropertyKey, ...args: any[]): boolean;
+      /** Listen to an event on the component instance. */
+      on(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+      /** Listen to an event on the component instance once. */
+      once(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+      /** Listen to an event on the component instance before all other listeners. */
+      prependListener(
+        eventName: PropertyKey,
+        listener: (...args: any[]) => any,
+      ): this;
+      /** Remove a listener from the component instance. */
+      removeListener(
+        eventName: PropertyKey,
+        listener: (...args: any[]) => any,
+      ): this;
+      /** Remove all listeners from the component instance. */
+      removeAllListeners(eventName?: PropertyKey): this;
+      /** Removes the component instance from the DOM and cleans up all active event handlers including all children. */
+      destroy(): void;
+      /** Schedule an update (similar to if a state had been changed). */
+      forceUpdate(): void;
+      /** Generates a unique id derived from the current unique instance id (similar to :scoped in the template). */
+      elId(key?: string, index?: number): string;
+      /** @alias elId */
+      getElId(key?: string, index?: number): string;
+      /** Gets an element reference by its `key` attribute in the template. */
+      getEl<T extends Element | void = Element | void>(
+        key?: string,
+        index?: number,
+      ): T;
+      /** Gets all element references by their `key` attribute in the template. */
+      getEls<T extends Element[] = Element[]>(key: string): T;
+      /** Gets a component reference by its `key` attribute in the template. */
+      getComponent<T extends Component | void = Component | void>(
+        key: string,
+        index?: number,
+      ): T;
+      /** Gets all component references by their `key` attribute in the template. */
+      getComponents<T extends Component[] = Component[]>(key: string): T;
+      /** True if this instance has been removed from the dom. */
+      /** True if this instance is scheduled to rerender. */
+      isDestroyed(): boolean;
+      /** Replace the entire state object with a new one, removing old properties. */
+      replaceState(state: this["state"]): void;
+      /**
+       * Update a property on this.state (should prefer mutating this.state directly).
+       * When passed an object as the first argument, it will be merged into the state.
+       */
+      setState<Key extends PropertyKey>(
+        name: Key & keyof this["state"],
+        value: (this["state"] & Record<PropertyKey, unknown>)[Key],
+      ): void;
+      setState(value: Partial<this["state"]>): void;
+
+      /** Schedules an update related to a specific state property and optionally updates the value. */
+      setStateDirty<Key extends PropertyKey>(
+        name: Key & keyof this["state"],
+        value?: (this["state"] & Record<PropertyKey, unknown>)[Key],
+      ): void;
+      /** Synchronously flush any scheduled updates. */
+      update(): void;
+      /** Appends the dom for the current instance to a parent DOM element. */
+      appendTo(target: ParentNode): this;
+      /** Inserts the dom for the current instance after a sibling DOM element. */
+      insertAfter(target: ChildNode): this;
+      /** Inserts the dom for the current instance before a sibling DOM element. */
+      insertBefore(target: ChildNode): this;
+      /** Prepends the dom for the current instance to a parent DOM element. */
+      prependTo(target: ParentNode): this;
+      /** Replaces an existing DOM element with the dom for the current instance. */
+      replace(target: ChildNode): this;
+      /** Replaces the children of an existing DOM element with the dom for the current instance. */
+      replaceChildrenOf(target: ParentNode): this;
+      // /** Called when the component is first created. */
+      // onCreate?(input: this["input"], out: Marko.Out): void;
+      // /** Called every time the component receives input from it's parent. */
+      // onInput?(input: this["input"], out: Marko.Out): void | this["input"];
+      // /** Called after a component has successfully rendered, but before it's update has been applied to the dom. */
+      // onRender?(out: Marko.Out): void;
+      // /** Called after the first time the component renders and is attached to the dom. */
+      // onMount?(): void;
+      // /** Called when a components render has been applied to the DOM (excluding when it is initially mounted). */
+      // onUpdate?(): void;
+      // /** Called when a component is destroyed and removed from the dom. */
+      // onDestroy?(): void;
+    }
+
+    /** The top level api for a Marko Template. */
+    export abstract class Template<Input = unknown, Return = unknown> {
+      /** Creates a Marko compatible output stream. */
+      createOut(): Out;
+
+      /**
+       * The following types are processed up by the @marko/language-tools
+       * and inlined into the compiled template.
+       *
+       * This is done to support generics on each of these methods
+       * until TypeScript supports higher kinded types.
+       *
+       * https://github.com/microsoft/TypeScript/issues/1213
+       */
+
+      /** @marko-overload-start */
+      /** Asynchronously render the template. */
+      abstract render(
+        input: Marko.TemplateInput<Input>,
+        stream?: {
+          write: (chunk: string) => void;
+          end: (chunk?: string) => void;
+        },
+      ): Marko.Out<Marko.Component>;
+
+      /** Asynchronously render the template in buffered mode. */
+      abstract render(
+        input: Marko.TemplateInput<Input>,
+        cb?: (
+          err: Error | null,
+          result: Marko.RenderResult<Marko.Component>,
+        ) => void,
+      ): Marko.Out<Marko.Component>;
+
+      /** Synchronously render the template. */
+      abstract renderSync(
+        input: Marko.TemplateInput<Input>,
+      ): Marko.RenderResult<Marko.Component>;
+
+      /** Synchronously render a template to a string. */
+      abstract renderToString(input: Marko.TemplateInput<Input>): string;
+
+      /** Render a template and return a stream.Readable in nodejs or a ReadableStream in a web worker environment. */
+      abstract stream(
+        input: Marko.TemplateInput<Input>,
+      ): ReadableStream<string> & NodeJS.ReadableStream;
+
+      /** Render and attach the template to a DOM node. */
+      abstract mount(
+        input: Marko.TemplateInput<Input>,
+        reference: Node,
+        position?: "afterbegin" | "afterend" | "beforebegin" | "beforeend",
+      ): Marko.MountedTemplate<typeof input>;
+      /** @marko-overload-end */
+    }
+
+    export interface RenderResult<
+      out Component extends Marko.Component = Marko.Component,
+    > {
+      /** Returns the component created as a result of rendering the template. */
+      getComponent(): Component;
+      getComponents(selector?: any): any;
+      /** Triggers the mount lifecycle of a component without necessarily attaching it to the DOM. */
+      afterInsert(host?: any): this;
+      /** Gets the DOM node rendered by a template. */
+      getNode(host?: any): Node;
+      /** Gets the HTML output of the rendered template. */
+      toString(): string;
+      /** Appends the dom of the rendered template to a parent DOM element. */
+      appendTo(target: ParentNode): this;
+      /** Inserts the dom of the rendered template after a sibling DOM element. */
+      insertAfter(target: ChildNode): this;
+      /** Inserts the dom of the rendered template before a sibling DOM element. */
+      insertBefore(target: ChildNode): this;
+      /** Prepends the dom of the rendered template to a parent DOM element. */
+      prependTo(target: ParentNode): this;
+      /** Replaces an existing DOM element with the dom of the rendered template. */
+      replace(target: ChildNode): this;
+      /** Replaces the children of an existing DOM element with the dom of the rendered template. */
+      replaceChildrenOf(target: ParentNode): this;
+      out: Out<Component>;
+      /** @deprecated */
+      document: any;
+      /** @deprecated */
+      getOutput(): string;
+      /** @deprecated */
+      html: string;
+      /** @deprecated */
+      context: Out<Component>;
+    }
+
+    export interface Emitter {
+      listenerCount(eventName: PropertyKey): number;
+      emit(eventName: PropertyKey, ...args: any[]): boolean;
+      on(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+      once(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+      prependListener(
+        eventName: PropertyKey,
+        listener: (...args: any[]) => any,
+      ): this;
+      removeListener(
+        eventName: PropertyKey,
+        listener: (...args: any[]) => any,
+      ): this;
+      removeAllListeners(eventName?: PropertyKey): this;
+    }
+
+    export type AttrTag<T> = T & {
+      [Symbol.iterator](): Iterator<T>;
+    };
+
+    export interface NativeTag<
+      Input extends Record<string, any>,
+      Return extends Element,
+    > {
+      input: Input;
+      return: { value: () => Return };
+    }
+    export interface NativeTags {
+      [name: string]: NativeTag<Record<string, any>, Element>;
+    }
+
+    export type Input<Name> = 0 extends 1 & Name
+      ? any
+      : Name extends string
+        ? Name extends keyof NativeTags
+          ? NativeTags[Name]["input"]
+          : Record<string, unknown>
+        : Name extends
+              | Template<infer Input, any>
+              | { _(): () => (input: infer Input) => any }
+          ? Input
+          : Name extends Body<infer Args, any>
+            ? Args extends {
+                length: infer Length;
+              }
+              ? number extends Length
+                ? Args[0] | undefined
+                : 0 extends Length
+                  ? undefined
+                  : Args[0]
+              : never
+            : never;
+
+    export type Return<Name> = 0 extends 1 & Name
+      ? any
+      : Name extends string
+        ? Name extends keyof NativeTags
+          ? NativeTags[Name]["return"]
+          : () => Element
+        : Name extends
+              | { _(): () => (input: any) => { return: infer Return } }
+              | Template<any, infer Return>
+              | Body<any, infer Return>
+          ? Return
+          : never;
+
+    /** @deprecated @see {@link Marko.AttrTag} */
+    export type RepeatableAttrTag<T> = AttrTag<T>;
+
+    /** @deprecated @see {@link Marko.Input} */
+    export type NativeTagInput<Name extends keyof NativeTags> =
+      NativeTags[Name]["input"];
+    /** @deprecated @see {@link Marko.Return} */
+    export type NativeTagReturn<Name extends keyof NativeTags> =
+      NativeTags[Name]["return"];
+  }
+}

package/package.json

@@ -1 +1,35 @@
-{"name":"@marko/ts-plugin","version":"0.0.0","private":false}
+{
+  "name": "@marko/ts-plugin",
+  "version": "3.1.0",
+  "description": "TypeScript Server plugin that resolves Marko (.marko) imports with types inside TypeScript files",
+  "keywords": [
+    "marko",
+    "typescript",
+    "tsserver",
+    "plugin",
+    "tools"
+  ],
+  "homepage": "https://github.com/marko-js/language-server/tree/main/packages/ts-plugin/README.md",
+  "bugs": "https://github.com/marko-js/language-server/issues/new?template=bug-report.yml",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marko-js/language-server/tree/main/packages/ts-plugin"
+  },
+  "license": "MIT",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "!**/__tests__",
+    "!**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsx build.mts"
+  },
+  "devDependencies": {
+    "@marko/language-server": "^3.0.1",
+    "@marko/language-tools": "^2.5.59",
+    "marko": "^5.38.36",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  }
+}