@xanots/xanoscript 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+interface KindValue {
+    getKind(): string;
+    getType(): string;
+    getName(): string | null;
+    toString(): string;
+}
+
+interface Kind {
+    getKind(): string;
+    getLabels(): string[];
+    getType(): string;
+    getSchemaType(): unknown;
+    isNullable(): boolean;
+    parse(data: unknown): KindValue;
+}
+
+/**
+ * The mutable render flags the engine keeps in CoroutineState / statics.
+ *
+ * The PHP encoder reads a handful of process-wide switches while rendering:
+ * verbose (legacy `!var "x"` tags), the object-literal indent counter, the
+ * quote/multiline modes the parser honours, the forced-multiline switch, the
+ * pipe registry currently in effect, and the transform context stack. One
+ * emit call owns this state for its duration; `withRenderState` snapshots and
+ * restores it so nested or sequential emits never leak flags into each other.
+ */
+type PipeMode = "pipes" | "filters" | "aggregates";
+interface RenderState {
+    /** the engine's `isVerbose()` — legacy tagged rendering. Production output is minimal. */
+    verbose: boolean;
+    /** `Script.INDEX` — nesting depth while wrapping object/array literals. */
+    index: number;
+    /** `Parser.QUOTE_MODE` — force a quote character for text (tests only). */
+    quoteMode: '"' | "'" | null;
+    /** `Parser.QUOTE_MULTILINE` — allow `"""` blocks. */
+    multilineQuotes: boolean;
+    /** `Parser.TICK_MULTILINE` — allow ```` ``` ```` blocks. */
+    multilineTicks: boolean;
+    /** `MultiLineValue.FORCE` — always emit block syntax for multi-line text. */
+    multilineForce: boolean;
+    /** `Transform::$PIPE_MODE` — which registry resolves pipe display names. */
+    pipeMode: PipeMode;
+    /** `Transform::$CONTEXT` — the object being encoded (mocks resolve test names off it). */
+    contextStack: unknown[];
+}
+
+/** the engine — export-time switches. */
+type Feature = "guid" | "workspaceEnv" | "tableItems";
+/** A name → id map, or a lazy loader for one. */
+type NameMap = Record<string, unknown> | (() => Record<string, unknown>);
+/** The id → name maps the emitter resolves references through. */
+interface ScriptMaps {
+    function?: Record<string, unknown>;
+    workflowTest?: Record<string, unknown>;
+    app?: Record<string, unknown>;
+    /** Keyed `name|verb|app.id`. */
+    query?: Record<string, unknown>;
+    dbo?: Record<string, unknown>;
+    addon?: Record<string, unknown>;
+    task?: Record<string, unknown>;
+    trigger?: Record<string, unknown>;
+    tool?: Record<string, unknown>;
+    toolset?: Record<string, unknown>;
+    middleware?: Record<string, unknown>;
+    /** v1 realtime channels, keyed by pattern. */
+    channel?: Record<string, unknown>;
+    realtimeServer?: Record<string, unknown>;
+    /** v2 channels, keyed `server|path`. */
+    v2Channel?: Record<string, unknown>;
+    /** Keyed `name|channel.id`. */
+    message?: Record<string, unknown>;
+    action?: Record<string, unknown>;
+    actionPackage?: Record<string, unknown>;
+}
+declare class ScriptContext {
+    private kinds;
+    private aliases;
+    private features;
+    private maps;
+    /** Every reference a render could not name — the diagnostic `compile --format xs` reports. */
+    private unresolved;
+    private readonly pipes;
+    constructor();
+    private registerKindAssign;
+    private registerKindStatic;
+    private registerKindSchema;
+    registerKind(kind: Kind): void;
+    setAlias(kind: string, alias: string): void;
+    getAlias(alias: string): string | null;
+    getKind(kind: string): Kind;
+    /** Kind names carrying ALL the given labels, in registration order. */
+    getKinds(labels?: string[] | string): string[];
+    getFeature(feature: Feature): boolean;
+    setFeature(feature: Feature, value: boolean): void;
+    setFeatures(features: Record<Feature, boolean>): void;
+    registerMap(name: keyof ScriptMaps, map: NameMap): void;
+    /**
+     * Per-map reverse index (`String(id or alias)` → first name carrying it),
+     * built on first lookup and dropped when the map is replaced. A multidoc
+     * resolves one reference per statement against maps holding every object of
+     * the workspace, so the plain scan is O(references × objects); the index is
+     * the same answer in O(1) for the string/number ids every map carries. The
+     * loose scan remains the fallback for the rest ("05" is 5 to the engine).
+     */
+    private reverse;
+    private reverseIndex;
+    /** The map key whose value (or alias) equals `id`, by index first, then by the engine's loose compare. */
+    private keyForId;
+    registerMaps(maps: ScriptMaps): void;
+    getMap(name: keyof ScriptMaps): Record<string, unknown>;
+    /** The references no map could name since the last call, oldest first; clears the record. */
+    takeUnresolved(): Array<{
+        label: string;
+        id: unknown;
+    }>;
+    /**
+     * A map value is the object's id, or a list of aliases for it: an SDK bundle
+     * references objects by guid while a pulled workspace uses numeric ids, so a
+     * row that carries both registers both and resolves from either.
+     */
+    private idToName;
+    mapIdToFunctionName(id: unknown): string;
+    mapIdToWorkflowTestName(id: unknown): string;
+    mapIdToAppName(id: unknown, doThrow?: boolean): string;
+    mapIdToQuery(id: unknown): string;
+    parseQuery(query: string): {
+        name: string;
+        verb: string;
+        appId: string;
+    };
+    mapIdToDboName(id: unknown, doThrow?: boolean): string;
+    mapIdToAddonName(id: unknown): string;
+    mapIdToTaskName(id: unknown): string;
+    mapIdToTriggerName(id: unknown): string;
+    mapIdToToolName(id: unknown): string;
+    mapIdToToolsetName(id: unknown, doThrow?: boolean): string;
+    mapIdToMiddlewareName(id: unknown): string;
+    mapIdToChannelName(id: unknown, doThrow?: boolean): string;
+    mapIdToRealtimeServerName(id: unknown, doThrow?: boolean): string;
+    v2ChannelMapKey(serverName: unknown, channelPath: unknown): string;
+    mapIdToV2ChannelName(id: unknown, doThrow?: boolean): string;
+    mapIdToV2ChannelServerName(id: unknown, doThrow?: boolean): string;
+    actionNameOf(id: unknown): string;
+    actionPackageNameOf(id: unknown): string;
+    /** `setV2Channel`: key by `{serverName}|{path}` resolving the server through the server map. */
+    setV2Channel(map: Record<string, unknown>, item: {
+        id: unknown;
+        name: string;
+        server?: {
+            id?: unknown;
+        };
+    }): void;
+    getPipeDisplay(mode: PipeMode, name: string): string | null;
+    getPipeInternalNames(mode: PipeMode): string[];
+}
+
+type Row = Record<string, unknown>;
+interface MultidocSections {
+    workspace?: Row;
+    dbo?: Row[];
+    function?: Row[];
+    middleware?: Row[];
+    app?: Row[];
+    query?: Row[];
+    task?: Row[];
+    addon?: Row[];
+    toolset?: Row[];
+    tool?: Row[];
+    trigger?: Row[];
+    workflow_test?: Row[];
+    realtime_server?: Row[];
+    channel?: Row[];
+    message?: Row[];
+    microservice?: Row[];
+    [key: string]: unknown;
+}
+interface MultidocOptions {
+    /** Which document groups to emit; everything defaults to on. */
+    include?: Partial<Record<"table" | "function" | "query" | "task" | "addon" | "middleware" | "ai" | "action" | "workflow_test" | "trigger" | "realtime" | "realtime_v2" | "microservice", boolean>>;
+    /** Engine export features: `guid` lines, workspace `env`, table `items` (records). */
+    features?: Partial<Record<Feature, boolean>>;
+    /** Extra name → id entries laid over the maps derived from the payload (a reference to an object outside it). */
+    maps?: ScriptMaps;
+    /** Reuse a prepared context. */
+    context?: ScriptContext;
+}
+declare function emitWorkspaceMultidoc(input: MultidocSections | {
+    payload: MultidocSections;
+}, options?: MultidocOptions): string;
+
+/** A document's header facts, as the CLI reads them off the text. */
+interface ParsedDocument {
+    apiGroup?: string;
+    canonical?: string;
+    /** Owning channel path for realtime v2 `message` documents. */
+    channel?: string;
+    content: string;
+    guid?: string;
+    name: string;
+    /** Owning realtime_server name for realtime v2 `channel` documents. */
+    server?: string;
+    type: string;
+    verb?: string;
+}
+/** A document's resolved location relative to the tree root, plus its content. */
+interface PlacedDocument {
+    content: string;
+    /** POSIX-style path relative to the root, e.g. `api/pdf/documents_GET.xs`. */
+    relPath: string;
+}
+/**
+ * Parse one document's type, name and the references its placement needs.
+ * Leading `//` comment lines are skipped to find the declaration.
+ */
+declare function parseDocument(content: string): ParsedDocument | null;
+/** Split a multidoc into parsed documents, skipping empties and unparseable fragments. */
+declare function splitMultidoc(blob: string): ParsedDocument[];
+/**
+ * Where each document of a batch lands: `resolveDocumentPath` plus the `.xs`
+ * extension, with a `_N` suffix on a second document that would take a name
+ * already used in the same directory (`say.xs`, then `say_2.xs`).
+ */
+declare function placeDocuments(documents: ParsedDocument[]): PlacedDocument[];
+/** A multidoc as the files `xano workspace pull` would write for it. */
+declare function placeMultidoc(multidoc: string): PlacedDocument[];
+/**
+ * The top-level directories the layout can write into, derived from the
+ * placement rules themselves (each type placed with and without the references
+ * that change its home), so a writer that owns the tree prunes every directory
+ * a document could have landed in.
+ */
+declare function layoutRoots(): string[];
+
+interface EmitOptions {
+    /** id → name maps for every cross-reference the object makes. */
+    maps?: ScriptMaps;
+    /** Engine export features (`guid` emits guid lines, etc.). */
+    features?: Partial<Record<Feature, boolean>>;
+    /** Render flags; the defaults are what the engine's export path uses. */
+    render?: Partial<Omit<RenderState, "index" | "contextStack" | "pipeMode">>;
+    /** Reuse a prepared context (its maps stay registered across calls). */
+    context?: ScriptContext;
+}
+/** A context with the vendored engine kinds loaded; cached because the registry is large. */
+declare function createScriptContext(maps?: ScriptMaps, features?: Partial<Record<Feature, boolean>>): ScriptContext;
+/** Render one object (`schema:function`, `schema:query`, a statement kind, …) to XanoScript. */
+declare function emitXanoScript(kind: string, data: unknown, options?: EmitOptions): string;
+
+export { type EmitOptions, type Feature, type MultidocOptions, type MultidocSections, type ParsedDocument, type PlacedDocument, ScriptContext, type ScriptMaps, createScriptContext, emitWorkspaceMultidoc, emitXanoScript, layoutRoots, parseDocument, placeDocuments, placeMultidoc, splitMultidoc };

package/dist/index.js

@@ -0,0 +1,67 @@
+import {
+  ScriptContext,
+  emitWorkspaceMultidoc,
+  layoutRoots,
+  parseDocument,
+  placeDocuments,
+  placeMultidoc,
+  processConvert,
+  splitMultidoc,
+  withRenderState,
+  withScriptContext
+} from "./chunk-677U72GF.js";
+
+// src/index.ts
+var shared = null;
+function createScriptContext(maps, features) {
+  const ctx = new ScriptContext();
+  if (maps) ctx.registerMaps(maps);
+  if (features) {
+    for (const [k, v] of Object.entries(features)) ctx.setFeature(k, Boolean(v));
+  }
+  return ctx;
+}
+function contextFor(o) {
+  if (o.context) {
+    if (o.maps) o.context.registerMaps(o.maps);
+    if (o.features) o.context.setFeatures({ guid: false, workspaceEnv: false, tableItems: false, ...o.features });
+    return o.context;
+  }
+  if (o.maps) return createScriptContext(o.maps, { guid: false, workspaceEnv: false, tableItems: false, ...o.features ?? {} });
+  if (!shared) shared = new ScriptContext();
+  shared.setFeatures({ guid: false, workspaceEnv: false, tableItems: false, ...o.features ?? {} });
+  return shared;
+}
+function emitXanoScript(kind, data, options = {}) {
+  const ctx = contextFor(options);
+  const out = withScriptContext(
+    ctx,
+    () => withRenderState(
+      {
+        verbose: false,
+        quoteMode: null,
+        multilineQuotes: true,
+        multilineTicks: true,
+        multilineForce: false,
+        pipeMode: "pipes",
+        index: 0,
+        ...options.render ?? {}
+      },
+      () => processConvert(kind, data).output
+    )
+  );
+  if (!options.context) ctx.takeUnresolved();
+  return out;
+}
+export {
+  ScriptContext,
+  createScriptContext,
+  emitWorkspaceMultidoc,
+  emitXanoScript,
+  layoutRoots,
+  parseDocument,
+  placeDocuments,
+  placeMultidoc,
+  splitMultidoc
+};
+//# sourceMappingURL=index.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,30 @@
+import { ToolchainPlugin } from '@xanots/sdk/plugin';
+
+/** The range as `package.json` spells it, so one edit cannot move without the other. */
+declare const PEER_RANGE = ">=0.0.29 <0.1.0";
+/**
+ * Refuse, by name and before any work, an SDK this module does not understand.
+ *
+ * The install-time peer warning cannot carry this: the peer is declared
+ * non-optional precisely so npm prints one, but a warning during `npm install`
+ * is read by nobody three weeks later, and the failure it describes is SILENT —
+ * an older SDK has no toolchain loader at all, so the hook simply never fires
+ * and the tree quietly stops being written. A hook that DID fire on a version
+ * outside the range is the case this catches: the shapes it is handed are not
+ * the shapes it was written against.
+ *
+ * An unparsable version, or one carrying a PRERELEASE suffix, is allowed
+ * through. The SDK reads the version from its own `package.json`, and a source
+ * checkout reads `0.0.0-dev` — refusing that would break exactly the linked
+ * development setup KTD5 asks for. The cost is that a prerelease of an
+ * out-of-range SDK is not caught, which is the trade npm's own ranges make.
+ */
+declare function assertSdkVersion(sdkVersion: string): void;
+/**
+ * The default export the SDK's loader reads. `kind` is repeated from the
+ * manifest so the two must agree — a mismatch means one of them is stale, and
+ * guessing which would run code the manifest did not describe.
+ */
+declare const plugin: ToolchainPlugin;
+
+export { PEER_RANGE, assertSdkVersion, plugin as default };