@aldel/test-func-kit 0.0.1 → 0.0.3

package/README.md

@@ -1,3 +1,66 @@
 # test-func-kit
 
-A minimal, experimental Firebase Function Kit.
+A minimal, experimental Firebase Function Kit. Has one parameter, `MESSAGE`,
+and one function, `helloWorld`, an HTTPS endpoint that returns the value of `MESSAGE`.
+
+Function kits are very new, and the only existing documentation is steps for
+converting a Firebase Extension to a kit. This is a kit that I created to try
+to understand more about how they work.
+
+Earlier I made [this repo](https://github.com/adelespinasse/funckittest), which
+is just a simple Firebase project with one kit installed, so I could see what
+installation does.
+
+### How kits work
+
+Based on the conversion instructions and the only existing kit that I'm aware
+of
+([@firebase-function-kits/firestore-bigquery-export](https://www.npmjs.com/package/@firebase-function-kits/firestore-bigquery-export)),
+a function kits appears to consist of:
+
+* A straightforward extension of the [codebases and function groups
+  features](https://firebase.google.com/docs/functions/organize-functions#organize_functions_in_codebases),
+  where you can list a "kit" in the functions section of firebase.json instead
+  of a "codebase", and it automatically adds a prefix to each of the exported
+  functions, and loads parameters from a named config for that installation
+* The functions:kits:install command, which creates a whole new npm package
+  under function-kits/ (parallel to functions/, not nested under it), installs
+  the package you name there, generates a wrapper to import and re-export its
+  functions, adds the necessary "kit" entry to firebase.json, prompts for
+  parameter values, and creates the named .env file for the parameters
+* [Lifecycle
+  triggers](https://firebase.google.com/docs/extensions/publishers/migrate#convert-lifecycle-hooks)
+  to replace the Extensions install/upgrade hooks
+* A way to [declare required APIs and service account roles in the
+  code]()https://firebase.google.com/docs/extensions/publishers/migrate#declare-apis-and-roles
+
+I'm probably missing things.
+
+Compared with Extensions, kits lose the "app store" type of registry, which has
+advantages and disadvantages: it helps users discover extensions and have
+confidence in them, but also is a barrier to entry for extension developers,
+and requires that extensions be open source and Apache licensed. Kits just use
+the npm free-for-all model.
+
+### Lessons learned
+
+* It appears to be impossible to install a kit that isn't published on a
+  registry. The `firebase functions:kits:install --package` command doesn't
+  work with other package specifiers, like a tarball or path to a directory.
+  There is a `--directory` option you can use instead of `--package`, but it
+  doesn't appear to work, at least not as I expected. This makes testing hard,
+  and hopefully will be fixed.
+* There are also `functions:kits:uninstall` and `functions:kits:list` commands,
+  which work as you would expect.
+* Always generate `.d.ts` files for your kit's package. The installation
+  process generates TypeScript wrapper code that is compiled with `tsc`, which
+  fails when it tries to import from the kit if there are no type definitions.
+  (Or maybe you could just have the package.json "main" property point to a
+  TypeScript file? Since it's running the compiler anyway...)
+* Don't call `setGlobalOptions` in a kit. The generated wrapper calls it, and
+  calling it twice generates a warning; apparently it "leads to undefined
+  behavior". Also it doesn't really make sense to call it, I guess. It wouldn't
+  have occurred to me to call it, but it's called in the default functions code
+  generated by `firebase init`, and I hadn't thought to remove it.
+
+

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Minimal Function Kit function with one parameter
+ */
+export declare const helloWorld: import("firebase-functions/https").HttpsFunction;

package/lib/index.js

@@ -1,18 +1,12 @@
 "use strict";
 /**
- * Import function triggers from their respective submodules:
- *
- * import {onCall} from "firebase-functions/v2/https";
- * import {onDocumentWritten} from "firebase-functions/v2/firestore";
- *
- * See a full list of supported triggers at https://firebase.google.com/docs/functions
+ * Minimal Function Kit function with one parameter
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.helloWorld = void 0;
-const firebase_functions_1 = require("firebase-functions");
+// import {setGlobalOptions} from "firebase-functions";
 const https_1 = require("firebase-functions/https");
 const params_1 = require("firebase-functions/params");
-// import * as logger from "firebase-functions/logger";
 const message = (0, params_1.defineString)('MESSAGE', {
     label: 'Message sent by the helloWorld function',
     description: 'The message to be sent by the helloWorld function. Must begin with "Hello".',
@@ -24,19 +18,10 @@ const message = (0, params_1.defineString)('MESSAGE', {
         },
     },
 });
-// Start writing functions
-// https://firebase.google.com/docs/functions/typescript
-// For cost control, you can set the maximum number of containers that can be
-// running at the same time. This helps mitigate the impact of unexpected
-// traffic spikes by instead downgrading performance. This limit is a
-// per-function limit. You can override the limit for each function using the
-// `maxInstances` option in the function's options, e.g.
-// `onRequest({ maxInstances: 5 }, (req, res) => { ... })`.
-// NOTE: setGlobalOptions does not apply to functions using the v1 API. V1
-// functions should each use functions.runWith({ maxInstances: 10 }) instead.
-// In the v1 API, each function can only serve one request per container, so
-// this will be the maximum concurrent request count.
-(0, firebase_functions_1.setGlobalOptions)({ maxInstances: 10 });
+// NOTE: Don't call setGlobalOptions in a function kit; the generated wrapper
+// calls it, and calling twice outputs a warning ("leads to undefined
+// behavior").
+//setGlobalOptions({maxInstances: 10});
 exports.helloWorld = (0, https_1.onRequest)((request, response) => {
     console.log("Hello logs!", { structuredData: true });
     response.send(message.value());

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,uDAAuD;AACvD,oDAAmD;AACnD,sDAAyD;AAEzD,MAAM,OAAO,GAAG,IAAA,qBAAY,EAC1B,SAAS,EACT;IACE,KAAK,EAAE,yCAAyC;IAChD,WAAW,EAAE,6EAA6E;IAC1F,OAAO,EAAE,eAAe;IACxB,KAAK,EAAE;QACL,IAAI,EAAE;YACJ,eAAe,EAAE,WAAW;YAC5B,sBAAsB,EAAE,yBAAyB;SAClD;KACF;CACF,CACF,CAAC;AAEF,6EAA6E;AAC7E,qEAAqE;AACrE,cAAc;AACd,uCAAuC;AAE1B,QAAA,UAAU,GAAG,IAAA,iBAAS,EAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;IACxD,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,EAAC,cAAc,EAAE,IAAI,EAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;AACjC,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@aldel/test-func-kit",
   "description": "A minimal, experimental function kit for Firebase.",
-  "version": "0.0.1",
+  "version": "0.0.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adelespinasse/test-func-kit.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +24,7 @@
     "node": "24"
   },
   "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "dependencies": {
     "firebase-admin": "^13.6.0",
     "firebase-functions": "^7.0.0"

package/src/index.ts

@@ -1,16 +1,10 @@
 /**
- * Import function triggers from their respective submodules:
- *
- * import {onCall} from "firebase-functions/v2/https";
- * import {onDocumentWritten} from "firebase-functions/v2/firestore";
- *
- * See a full list of supported triggers at https://firebase.google.com/docs/functions
+ * Minimal Function Kit function with one parameter
  */
 
-import {setGlobalOptions} from "firebase-functions";
+// import {setGlobalOptions} from "firebase-functions";
 import {onRequest} from "firebase-functions/https";
 import { defineString } from 'firebase-functions/params';
-// import * as logger from "firebase-functions/logger";
 
 const message = defineString(
   'MESSAGE',
@@ -27,21 +21,10 @@ const message = defineString(
   },
 );
 
-
-// Start writing functions
-// https://firebase.google.com/docs/functions/typescript
-
-// For cost control, you can set the maximum number of containers that can be
-// running at the same time. This helps mitigate the impact of unexpected
-// traffic spikes by instead downgrading performance. This limit is a
-// per-function limit. You can override the limit for each function using the
-// `maxInstances` option in the function's options, e.g.
-// `onRequest({ maxInstances: 5 }, (req, res) => { ... })`.
-// NOTE: setGlobalOptions does not apply to functions using the v1 API. V1
-// functions should each use functions.runWith({ maxInstances: 10 }) instead.
-// In the v1 API, each function can only serve one request per container, so
-// this will be the maximum concurrent request count.
-setGlobalOptions({maxInstances: 10});
+// NOTE: Don't call setGlobalOptions in a function kit; the generated wrapper
+// calls it, and calling twice outputs a warning ("leads to undefined
+// behavior").
+//setGlobalOptions({maxInstances: 10});
 
 export const helloWorld = onRequest((request, response) => {
   console.log("Hello logs!", {structuredData: true});

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "module": "NodeNext",
+    "declaration": true,
     "esModuleInterop": true,
     "moduleResolution": "nodenext",
     "noImplicitReturns": true,