@zapier/kitcore 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # @zapier/kitcore
 
+## 0.21.0
+
+### Minor Changes
+
+- 2102c00: **Removed the legacy function-plugin bridge.** A plugin is now always a
+  descriptor built by `define*` / `declare*`, never a `(sdk) => provides`
+  function. These exits shipped deprecated with runtime warnings in 0.5.0 and are
+  now gone:
+
+  | Removed                                                                           | Use instead                                                             |
+  | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+  | `createPluginStack`, `composePlugins`                                             | `definePlugin({ name, exports })` and `createSdk(root)`                 |
+  | `createPluginMethod`, `createPaginatedPluginMethod`                               | `defineMethod({ output: "item" })` / `defineMethod({ output: "list" })` |
+  | `createCorePlugin(options)`                                                       | `createSdk(root, { configuration: { [CORE_OPTIONS_ID]: options } })`    |
+  | `fromFunctionPlugin`, `defineLegacyMerge`                                         | `createSdk(root)` on a descriptor root                                  |
+  | `definePlugin(fn)` (the function form)                                            | `defineMethod` / `defineProperty` / `definePlugin({ ... })`             |
+  | `Plugin<TSdk, TProvides>` (the function-plugin type)                              | `Plugin` now names the descriptor a `define*` call returns              |
+  | `PluginProvides`, `Sdk`, `PluginStack`, `LegacyPlugin`, `LegacyMergePlugin` types | `PluginSurface<typeof plugin>` for a plugin's own surface               |
+  | `OutputFormatter` type                                                            | `defineFormatter`, whose result is a `Formatter`                        |
+
+  Also removed, with no deprecation warning: `createFunction`,
+  `createPaginatedFunction`, and the `AdaptPage` type. Only a function plugin
+  could use their output. Author with `defineMethod({ output: "item" })` or
+  `defineMethod({ output: "list" })` instead.
+
+  Consequences for code that builds with `createSdk`:
+  - `addPlugin(sdk, plugin)` types `plugin` as a descriptor, so a function or
+    any other non-plugin no longer compiles, and it refuses one at runtime too.
+  - `context.meta` and `context.core` are gone. Read metadata with
+    `getRegistry(sdk)`, and inject framework options under `CORE_OPTIONS_ID`.
+  - `SdkContext` has no index signature, so `sdk.context.anything` no longer
+    typechecks.
+  - Description fields live flat on the descriptor, as the author wrote them,
+    and flat on the built entry, like its runtime fields. There is no `meta` bag
+    on either any more. A `defineOverride` carries its fields as
+    `MethodOverridePlugin.patch` and writes them into the entry, so the
+    descriptor still shows what the author wrote.
+  - The description fields split by kind. `PropertyMeta` is what any leaf can
+    carry: `description`, `categories`, `packages`, `stability`, `experimental`,
+    `deprecation`. `MethodMeta` extends it with what only a callable has: `type`,
+    `itemType`, `returnType`, `confirm`, `aliases`, `supportsJsonOutput`. A
+    property config no longer accepts `aliases`, and a `defineOverride` patch is
+    typed as `OverridableMetaFields` instead of the whole bag. `PluginMeta` and
+    `LeafMeta` are deprecated aliases of `MethodMeta`. Gone from all of them:
+    `formatter`, `resolvers`, the `TSdk` type parameter, `inputSchema` and
+    `outputSchema` (method fields, since they drive validation), and the
+    `[key: string]: any` index signature, so an unknown field no longer compiles.
+    `skipOutputValidation` is a runtime switch and lives on the method config
+    beside `skipInputValidation`.
+  - Every descriptor kind extends `PluginBase` (`pluginType`, `name`,
+    `namespace`, `id`, `imports`, `importBindings`). Methods and properties extend
+    `LeafBase` (stand-in and default markers, `setup`, `dispose`), and a hook adds
+    `PluginLifecycle`. `PluginType` names the discriminant union. No shape
+    changed; the shared fields are declared once.
+  - Pagination helpers are exported by name rather than through a wildcard. The
+    helpers themselves are unchanged.
+  - `getRegistry` is no longer a reserved root key. `context` still is, and
+    `createSdk` now refuses it for a root too, not only `addPlugin`.
+
+  Errors that used to surface as a `TypeError` about a kitcore internal now name
+  the mistake:
+  - `getContext(sdk)` and `getRegistry(sdk)` throw `CoreErrorCode.NoSdkContext`
+    when the object has no plugin graph. `getRegistry(sdk)` still falls back to a
+    surfaced `getRegistry()` first.
+  - `createSdk` and `addPlugin` refuse a non-descriptor, a `declare*` stand-in,
+    and any `pluginType` the model does not build. An extension built against a
+    kitcore that still had the bridge fails this way, with
+    `unknown pluginType "legacy"`, and must be rebuilt against this release.
+    Nested plugins are checked too, and `definePlugin`, `defineMethod`,
+    `defineProperty`, and `defineHook` check each `imports` and `exports` entry as
+    it is written.
+
+  `context.plugins` now holds every plugin in the graph. A hook and a
+  `defineOverride` have entries too, with no value, and every entry carries
+  `descriptor`, the plugin object it was built from.
+
+  `addPlugin` is transactional and checks identity:
+  - A failed add rolls back everything it wrote and rethrows the original error.
+    A `dispose` registered by a `setup` that completed runs during the rollback.
+    Only its synchronous part is guaranteed, so release before the first `await`.
+  - A plugin whose id another plugin already claimed is refused instead of being
+    dropped silently. Re-adding the same descriptor still works, as does a
+    provider for an optional stand-in that nothing satisfied. Two overrides of
+    one method need distinct `namespace`s. A provider for an id a `declareDefault`
+    claimed belongs in the `createSdk` graph.
+
+  `Plugin` is the type of any `define*` result, for typing a slot that accepts
+  plugins. It replaces the function-plugin type of the same name.
+
+  Fixed: an inline `define*` call inside `definePlugin({ exports: [...] })` keeps
+  its inferred types instead of widening `input` to `any`.
+
+  Fixed: a plugin named `__proto__` replaced the prototype of kitcore's internal
+  plugin table instead of being stored. Every table kitcore keys by an
+  author-chosen name (plugin id, binding name) is now created without a
+  prototype, so any `Object.prototype` member name (`toString`, `constructor`,
+  `__proto__`) is an ordinary plugin name.
+
 ## 0.20.0
 
 ### Minor Changes

package/README.md

@@ -366,7 +366,7 @@ Re-export the built-in `getRegistryPlugin` if you also want a `getRegistry()` me
 
 The result is memoized per SDK and per package filter, and `addPlugin` drops it, so a registry read still reflects anything added after the build. Because every reader shares that one object, its `functions` and `categories` arrays are frozen: copy before sorting or filtering in place.
 
-That holds for an SDK with a kitcore context, which is anything `createSdk` built. An SDK without one, meaning a `createPluginStack()` build, has no memo to share: `getRegistry(sdk)` forwards to the SDK's own `getRegistry()` and hands back whatever it builds, fresh and mutable on every call.
+That holds for an SDK with a kitcore context, which is anything `createSdk` built. An object without one that still surfaces its own `getRegistry()`, such as a test stub or a wrapper projecting someone else's registry, has no memo to share: `getRegistry(sdk)` forwards to that accessor and hands back whatever it builds, fresh and mutable on every call.
 
 ## Resolving inputs: controllers